欢迎使用PyFilesystem2的文档！

目录:

介绍

PyFilesystem是一个Python模块，为任何文件系统提供一个通用接口。

将PyFilesystem FS 对象视为Python的 file 对象的下一个逻辑步骤。 以同样的方式，文件对象抽象单个文件，FS 对象抽象整个文件系统。

安装

你可以使用 pip 安装PyFilesystem如下:

pip install fs

或升级到最新版本:

pip install fs --upgrade

或者，如果你想从源代码安装，你可以查看 Github上的代码。

指南

PyFilesytem 接口简化了处理文件和目录的大多数方面。本指南涵盖了使用 FS 对象所需的知识。

为什么要使用PyFilesystem？

如果你很习惯使用Python标准库，你可能会想： 为什么要学习另一个API来处理文件？

PyFilesystem API通常比 os 和 io 模块更简单 - 有更少的边缘情况和更少的方法来拍摄自己在脚。这可能是使用它的原因，但还有其他令人信服的理由，你应该使用 import fs 甚至直接的文件系统代码。

FS对象提供的抽象意味着您可以编写与您的文件物 理位置无关的代码。例如，如果您编写了一个函数来搜索目录中的重复文件，它将在硬盘驱动器上的目录，zip文件，FTP服务器，Amazon S3等上正常工作。

只要所选文件系统（或类似于文件系统的任何数据存储）存在FS对象，就可以使用相同的API。这意味着您可以将有关将数据存储在何处的决定推迟到以后。如果你决定将配置存储在 cloud 中，它可能是一个单行更改，而不是主要的重构。

PyFilesystem也可以有益于单元测试; 通过将OS文件系统与内存文件系统交换，您可以编写测试而无需管理（或模拟）文件IO。 您可以确保您的代码将在Linux，MacOS和Windows上工作。

打开文件系统

有两种方法可以打开文件系统。 第一种也是最自然的方法是导入合适的文件系统类并构造它。

下面是如何打开一个 OSFS （操作系统文件系统），它映射到硬盘驱动器的文件和目录:

>>> from fs.osfs import OSFS
>>> home_fs = OSFS("~/")

这构造了一个FS对象，它管理给定系统路径下的文件和目录。 在这种情况下， `〜/' ，这是你的主目录的快捷方式。

下面是如何列出主目录中的文件/目录:

>>> home_fs.listdir('/')
['world domination.doc', 'paella-recipe.txt', 'jokes.txt', 'projects']

请注意， listdir 的参数是一个单斜线，表示我们想要列出文件系统的 root 。 这是因为从 home_fs 的角度来看，根目录是我们用来构建 OSFS 的目录。

还要注意，它是一个正斜杠，即使在Windows上。 这是因为FS路径以一致的格式而与平台无关。 诸如分隔符和编码的细节被抽象化。 有关详细信息，请参阅 路径 。 其他文件系统接口可能对其构造函数有其他要求。 例如，这里是如何打开一个FTP文件系统:

>>> from ftpfs import FTPFS
>>> debian_fs = FTPFS('ftp.mirror.nl')
>>> debian_fs.listdir('/')
['debian-archive', 'debian-backports', 'debian', 'pub', 'robots.txt']

打开文件系统对象的第二种更通用的方法是通过 opener ，它从类似URL的语法中打开文件系统。 这里有一个替代方法来打开你的主目录:

>>> from fs import open_fs
>>> home_fs = open_fs('osfs://~/')
>>> home_fs.listdir('/')
['world domination.doc', 'paella-recipe.txt', 'jokes.txt', 'projects']

当您想要将应用程序文件的物理位置存储在配置文件中时，opener 系统特别有用。

如果不在FS URL中指定协议，那么PyFilesystem将假设您想要从当前工作目录获得OSFS相对路径。 所以下面是一个等效的打开你的主目录的方法:

>>> from fs import open_fs
>>> home_fs = open_fs('.')
>>> home_fs.listdir('/')
['world domination.doc', 'paella-recipe.txt', 'jokes.txt', 'projects']

树结构打印

调用FS对象上的 tree() 将打印文件系统的ascii树视图。 下面是一个例子:

>>> from fs import open_fs
>>> my_fs = open_fs('.')
>>> my_fs.tree()
├── locale
│   └── readme.txt
├── logic
│   ├── content.xml
│   ├── data.xml
│   ├── mountpoints.xml
│   └── readme.txt
├── lib.ini
└── readme.txt

这是一个有用的调试助手！

关闭

FS对象有一个 close() 方法，它将执行任何所需的清除操作。 对于许多文件系统（值得注意的是 OSFS ），close 方法很少。 其他文件系统只有在调用 close() 时才能完成文件或释放资源。

一旦使用完文件系统，你可以显式地调用 close 。 例如:

>>> home_fs = open_fs('osfs://~/')
>>> home_fs.settext('reminder.txt', 'buy coffee')
>>> home_fs.close()

如果使用FS对象作为上下文管理器，将自动调用 close 。 以下等同于前面的示例:

>>> with open_fs('osfs://~/') as home_fs:
...    home_fs.settext('reminder.txt', 'buy coffee')

建议使用FS对象作为上下文管理器，因为它将确保每个FS都关闭。

目录信息

文件系统对象有一个 listdir() 方法，类似于 os.listdir ; 它需要一个目录的路径并返回文件名列表。 下面是一个例子:

>>> home_fs.listdir('/projects')
['fs', 'moya', 'README.md']

存在列出目录的替代方法; scandir() 返回一个 iterable 的 资源信息 对象。 这里有一个例子:

>>> directory = list(home_fs.scandir('/projects'))
>>> directory
[<dir 'fs'>, <dir 'moya'>, <file 'README.md'>]

信息对象比文件名具有许多优点。 例如，你可以知道 info 对象是否引用一个文件或一个目录 is_dir 属性，而不需要额外的系统调用。 如果在 namespaces 参数中请求它，Info对象也可能包含诸如大小，修改时间等信息。

注解

scandir 返回一个可迭代而不是一个列表的原因是，如果目录非常大，或者如果必须通过网络检索信息，那么在块中检索目录信息可能更有效。

此外，FS对象有一个 filterdir() 方法扩展 scandir ，能够通过通配符过滤目录内容。 以下是如何在目录中找到所有Python文件的方法:

>>> code_fs = OSFS('~/projects/src')
>>> directory = list(code_fs.filterdir('/', files=['*.py']))

默认情况下，scandir 和 listdir 返回的资源信息对象只包含文件名和 is_dir 标志。您可以使用 namespaces 参数请求其他信息。以下是如何请求其他详细信息（例如文件大小和文件修改时间）:

>>> directory = code_fs.filterdir('/', files=['*.py'], namespaces=['details'])

这将向资源信息对象添加一个``size`` 和 modified 属性（和其他）。这使得像这样的代码:

>>> sum(info.size for info in directory)

有关详细信息，请参阅 资源信息 。

子目录

PyFilesystem没有 当前工作目录 的概念，所以你不会在FS对象上找到一个 chdir 方法。幸运的是你不会错过它;使用子目录是一个微风与PyFilesystem。

您可以随时使用接受路径的方法指定目录。例如， home_fs.listdir（'/ projects'） 会获得 projects 目录的目录列表。或者，您可以调用 opendir() ，它为子目录返回一个新的FS对象。

例如，以下是如何列出主目录中的`projects`文件夹的目录内容:

>>> home_fs = open_fs('~/')
>>> projects_fs = home_fs.opendir('/projects')
>>> projects_fs.listdir('/')
['fs', 'moya', 'README.md']

当你调用 opendir 时，FS对象返回一个 SubFS 的实例。 如果你调用一个 SubFS 对象的任何方法，它就好像你在父文件系统上调用了相对于子目录的路径相同的方法。 makedir 和 makedirs 方法也为新创建的目录返回 SubFS 对象。 下面是如何在 ~/projects 中创建一个新目录，并用几个文件初始化:

>>> home_fs = open_fs('~/')
>>> game_fs = home_fs.makedirs('projects/game')
>>> game_fs.touch('__init__.py')
>>> game_fs.settext('README.md', "Tetris clone")
>>> game_fs.listdir('/')
['__init__.py', 'README.md']

使用 SubFS 对象意味着你通常可以避免编写很多路径处理代码，这往往容易出错。

使用文件

您可以从FS对象打开一个文件 open() ，这与标准库中的 io.open 非常相似。 以下是如何在主目录中打开一个名为 reminder.txt 的文件:

>>> with open_fs('~/') as home_fs:
...     with home_fs.open('reminder.txt') as reminder_file:
...        print(reminder_file.read())
buy coffee

在 OSFS 的情况下，将返回标准的类文件对象。 其他文件系统可以返回支持相同方法的不同对象。 例如 MemoryFS 将返回一个 io.BytesIO 对象。

PyFilesystem还提供了许多常见文件相关操作的快捷方式。 例如 getbytes() 将以字节形式返回文件内容，而且 gettext 将读取unicode文本。 这些方法通常优于明确打开文件，因为FS对象可能具有优化的实现。

其他 快捷方式 是 setbin() ， setbytes() ， settext() 。

Walking

通常，您将需要扫描给定目录中的文件和任何子目录。 这被称为 walking 文件系统。

以下是如何打印主目录中所有Python文件的路径:

>>> from fs import open_fs
>>> home_fs = open_fs('~/')
>>> for path in home_fs.walk.files(filter=['*.py']):
...     print(path)

FS对象的 walk 属性是一个 BoundWalker 的实例，它应该能够处理大多数目录漫游需求。

参见 walk 有关walk目录的更多信息。

移动和复制

您可以使用 move() 和 copy() 方法移动和复制文件内容，并且等效 movedir() 和 copydir() 方法对目录而不是文件进行操作。

这些移动和复制方法在可能的情况下被优化，并且取决于实现，它们可以比读取和写入文件更高性能。

要在 文件系统之间移动和/或复制文件 （使用同一个文件系统），请使用 move 和 copy 模块。 这些模块中的方法接受FS对象和FS URLS。 例如，以下将压缩项目文件夹的内容:

>>> from fs.copy import copy_fs
>>> copy_fs('~/projects', 'zip://projects.zip')

这相当于下面这个例子，更冗长，代码:

>>> from fs.copy import copy_fs
>>> from fs.osfs import OSFS
>>> from fs.zipfs import ZipFS
>>> copy_fs(OSFS('~/projects'), ZipFS('projects.zip'))

copy_fs() 和 copy_dir() 函数也接受 Walker 参数，可以用来过滤将被复制的文件。 例如，如果你只想备份你的python文件，你可以使用像这样:

>>> from fs.copy import copy_fs
>>> from fs.walk import Walker
>>> copy_fs('~/projects', 'zip://projects.zip', walker=Walker(files=['*.py']))

概念

下面介绍使用PyFilesystem时的一些核心概念。 如果你在阅读本文档，请特别注意路径的第一部分。

路径

除了构造函数可能例外，文件系统中的所有路径都是 PyFilesystem paths ，它们具有以下属性：

  • 路径在Python3中是 str 类型，在Python2中是 unicode
  • 路径组件由正斜杠（ / ）分隔
  • 以 / 开头的路径是 绝对路径
  • 不以正斜杠开头的路径是 相对路径
  • 单个点（ . ）意味着 当前目录
  • 双点（ .. ）意味着 上级目录

请注意，FS接口使用的路径将使用此格式，但构造函数可能不使用。 值得注意的是 OSFS 构造函数，它需要一个操作系统路径 - 其格式是平台相关的。

注解

在 path 模块中有许多有用的函数用于处理路径。

PyFilesystem路径是与平台无关的，并且会自动转换为操作系统预期的格式 - 因此您不需要对文件系统代码进行任何修改，以使其在其他平台上运行。

系统路径

不是所有的Python模块都可以使用类似文件的对象，特别是那些与C库接口的对象。 对于这些情况，您将需要检索 系统路径 。您可以使用 getsyspath() 方法，将FS对象上下文中的有效路径转换为操作系统可以理解的绝对路径。

例如:

>>> from fs.osfs import OSFS
>>> home_fs = OSFS('~/')
>>> home_fs.getsyspath('test.txt')
'/home/will/test.txt'

不是所有的文件系统都映射到系统路径（例如： MemoryFS 中的文件将只存在于内存中）。

如果你在一个不映射到系统路径的文件系统上调用 getsyspath ，它将引发一个 NoSysPath() 异常。如果你喜欢跳回之前看的内容，你可以通过调用 hassyspath() 来检查资源是否有系统路径。

沙盒

FS对象不允许使用其 root 之外的任何文件。如果你试图打开文件系统实例之外的文件或目录（带有一个上级引用，如 "../ foo.txt" ），那么将抛出 IllegalBackReference 异常。这确保任何使用FS对象的代码将无法读取或修改您不想要的任何内容，从而限制任何出错范围。

与您的操作系统不同，PyFilesystem中没有当前工作目录的概念。如果要使用FS对象的子目录，可以使用 opendir() 方法，该方法返回表示该子目录的内容的另一个FS对象。

例如，考虑以下目录结构。目录 foo 包含两个子目录; bar 和 baz

--foo
  |--bar
  |  |--readme.txt
  |  `--photo.jpg
  `--baz
     |--private.txt
     `--dontopen.jpg

我们可以用下面的代码打开 foo 目录:

from fs.osfs import OSFS
foo_fs = OSFS('foo')

如果我们传递 foo_fs 一个有可能会删除文件的函数,``foo_fs`` 对象可以使用 bar 和 baz 的任何内容可能不是所期望的。幸运的是我们可以用一个子目录 opendir() 方法:

bar_fs = foo_fs.opendir('bar')

这将创建一个全新的FS对象，代表 foo / bar 目录中的所有内容。 bar_fs 的根目录已经被重新定位，所以从 bar_fs 的角度来看，readme.txt和photo.jpg文件在根目录下:

--bar
  |--readme.txt
  `--photo.jpg

注解

沙箱 只在你的代码使用本模块的文件系统接口时才有效。 它不会阻止使用标准操作系统级别文件操作的代码。

错误

PyFilesystem将错误转换为公共异常层次结构。 这确保错误处理代码可以写入一次，而不管使用的文件系统。 有关详细信息，请参阅 errors 。

资源信息

资源信息（或 info ）描述标准文件详细信息，例如名称，类型，大小等，以及潜在的其他不太常见的信息与文件或目录相关联。

您可以通过调用检索单个资源的资源信息 getinfo() ，或者通过调用 scandir() 它返回一个资源信息的迭代器的内容一个目录。 另外， filterdir() 可以在目录中按类型和通配符过滤资源。

以下是检索文件信息的示例:

>>> from fs.osfs import OSFS
>>> fs = OSFS('.')
>>> fs.settext('example.txt', 'Hello, World!')
>>> info = fs.getinfo('example.txt', namespaces=['details'])
>>> info.name
'example.txt'
>>> info.is_dir
False
>>> info.size
13

info 对象

PyFilesystem通过属性 Info 对象来公开资源信息。

命名空间

所有资源信息都包含在许多潜在的 命名空间 之中，这是逻辑 key/value 组。

你可以指定你感兴趣的命名空间作为位置参数 getinfo() 。 例如，以下检索文件的 details 和 access 命名空间:

resource_info = fs.getinfo('myfile.txt', 'details', 'access')

除了指定的命名空间之外，文件系统还将返回包含资源名称的 basic 命名空间，以及指示资源是否为目录的标志。

基本命名空间

始终返回 basic 命名空间。 它包含以下键：

名字 类型 描述
name str 资源名称
is_dir bool 一个布尔值，指示资源是否为目录

通常可以非常快速地检索此命名空间中的键。在 OSFS 的情况下，可以检索命名空间而不需要可能昂贵的系统调用。

详细命名空间

details 命名空间包含以下键。

名字 类型 描述
accessed datetime 文件上次访问的时间
created datetime 文件创建的时间
metadata_changed datetime 元数据 （e.g 所有者，组）的时间最近更改时间
modified datetime 最近更改文件数据时间
size int 用于存储资源的字节数。对象是文件时表示文件数据字节数，如果是目录 size 是用于存储目录条目的开销（以字节为单位）
type ResourceType 资源类型，其定义在 ResourceType

如果文件系统不存储该信息，则时间值（ accessible_time ， created_time 等）可以是 None 。如果文件系统无法检索资源类型, size 和 type 键保证可用，虽然 type 可能是 unknown 。

访问命名空间

access 命名空间报告权限和所有权信息，并包含以下键。

名字 类型 描述
gid int 组ID
group str 组名
permissions Permissions 一个实例 Permissions ，它包含资源的权限
uid int 用户ID
user str 所有者的用户名

此命名空间是可选的，因为并非所有文件系统都具有所有权或权限的概念。 它支持 OSFS 。 如果文件系统不支持，某些值可能是 None 。

Stat命名空间

stat 命名空间包含调用 os.stat 报告的信息。 这个命名空间支持 OSFS 和可能的其他文件系统，它们直接映射到操作系统文件系统。 大多数其他文件系统将不支持此命名空间。

其他命名空间

某些文件系统可能支持本文未涉及的其他命名空间。 有关支持哪些命名空间的信息，请参阅特定文件系统的文档。

您可以使用 get() 方法检索这种实现特定的资源信息。

注解

请求文件系统不支持的命名空间（或命名空间）不是错误。 任何未知的命名空间将被忽略。

原始信息

Info 类是一个包含 原始信息 的简单数据结构的包装器。 您可以使用 info.raw 属性访问此原始信息。

注解

如果你打算自己实现一个文件系统，以下是可能只有兴趣。

原始信息数据包括将命名空间名称映射到信息字典的字典。 下面是一个例子:

{
    'access': {
        'group': 'staff',
        'permissions': ['g_r', 'o_r', 'u_r', 'u_w'],
        'user': 'will'
    },
    'basic': {
        'is_dir': False,
        'name': 'README.txt'
    },
    'details': {
        'accessed': 1474979730.0,
        'created': 1462266356.0,
        'metadata_changed': 1473071537.0,
        'modified': 1462266356.0,
        'size': 79,
        'type': 2
    }
}

原始资源信息仅包含基本类型（字符串，数字，列表，字典，None）。这使得资源信息简单地通过网络发送，因为它可以被简单地串行化为JSON或其他数据格式。

由于这个要求，时间被存储为 epoch times 。 Info对象将把这些对象转换为来自标准库的datetime对象。 此外，Info对象会将权限从一个字符串列表转换为一个 fs.permissions.Permissions 对象。

FS URLs

PyFilesystem可以通过FS URL打开文件系统，这类似于您可能输入到浏览器的URL。

如果您希望能够在conf文件中（例如）动态指定文件系统，则使用FS URL可能非常有用。

FS URL将解析为以下格式:

<type>://<username>:<password>@<resource>

组件如下：

  • <type> 标识要创建的文件系统的类型。 例如 osfs , ftp 。
  • <username> 可选用户名。
  • <password> 可选密码。
  • <resource> resource，它可以是一个域，路径或两者。

以下是几个示例:

osfs://~/projects
osfs://c://system32
ftp://ftp.example.org/pub
mem://

如果 <类型> 没有指定是它被认为是一个 OSFS 。 以下FS URL等效:

osfs://~/projects
~/projects

要打开与FS URL的filesysem，你可以使用 open_fs()，它可以被导入和使用方法如下:

from fs import open_fs
projects_fs = open_fs('osfs://~/projects')

walk

walk 文件系统意味着递归地访问目录和任何子目录。这是复制，搜索等相当普遍的要求。

要走一个文件系统（或目录），你可以构造一个 Walker 对象，并使用它的方法来做行走。下面是一个打印项目目录中每个Python文件的路径的示例:

>>> from fs import open_fs
>>> from fs.walk import Walker
>>> home_fs = open_fs('~/projects')
>>> walker = Walker(filter=['*.py'])
>>> for path in walker.files(home_fs):
...     print(path)

然而，一般来说，如果你想定制步行算法的某些行为，你只需要构造一个Walker对象。这是因为你可以通过FS对象的 walk 属性来访问Walker对象的功能。下面是一个例子:

>>> from fs import open_fs
>>> home_fs = open_fs('~/projects')
>>> for path in home_fs.walk.files(filter=['*.py']):
...     print(path)

注意上面的 files 方法不需要 fs 参数。 这是因为 walk 属性是一个属性，它返回一个 BoundWalker 对象，它将文件系统与一个walker相关联。

walk 方法

如果你在一个 BoundWalker 上调用 walk 属性，它将返回一个可迭代的 Step 命名tuples有三个值;目录的路径，目录的一个列表 Info 对象，以及一个 Info 对象的列表。下面是一个例子:

for step in home_fs.walk(filter=['*.py']):
    print('In dir {}'.format(step.path))
    print('sub-directories: {!r}'.format(step.dirs))
    print('files: {!r}'.format(step.files))

注解

方法 BoundWalker 在 Walker 对象上调用相应的方法，使用 bound 文件系统。

walk 属性可能看起来是一个方法，但实际上是一个可调用的对象。它支持从步行提供不同信息的其他方便的方法。例如 files，它返回一个可迭代的文件路径。下面是一个例子:

for path in home_fs.walk.files(filter=['*.py']):
    print('Python file: {}'.format(path))

files 的称号是 dirs() ，它只返回目录的路径（忽略文件）。下面是一个例子:

for dir_path in home_fs.walk.dirs():
    print("{!r} contains sub-directory {}".format(home_fs, dir_path))

info() 方法返回一个包含一个路径和一个 Info 对象的元组生成器。您可以使用 is_dir 属性来了解路径是否指向目录或文件。下面是一个例子:

for path, info in home_fs.walk.info():
    if info.is_dir:
        print("[dir] {}".format(path))
    else:
        print("[file] {}".format(path))

最后，下面是一个很好的例子，它计算你的主目录中的Python代码的字节数:

bytes_of_python = sum(
    info.size
    for info in home_fs.walk.info(namespaces=['details'])
    if not info.is_dir
)

搜索算法

有两种用于搜索目录树的通用算法。第一种方法是“breadth”，它首先在目录树的顶部产生资源，然后进入子目录。第二个是“深度”，它产生最深的嵌套资源，并向后工作到最顶层目录。

一般来说，你只需要一个 depth 搜索，如果你将通过它们删除资源。默认 宽度 搜索是一种通常更有效的方式查看文件系统。你可以在大多数“Walker”方法中使用 search 参数指定你想要的方法。

内置文件系统

应用程序文件系统

用于特定于平台的应用程序目录的文件系统。

A collection of filesystems that map to application specific locations defined by the OS.

These classes abstract away the different requirements for user data across platforms, which vary in their conventions. They are all subclasses of OSFS.

class fs.appfs.UserDataFS(appname, author=None, version=None, roaming=False, create=True)

A filesystem for per-user application data.

参数:
  • appname (str) – The name of the application.
  • author (str) – The name of the author (used on Windows).
  • version (str) – Optional version string, if a unique location per version of the application is required.
  • roaming (bool) – If True, use a roaming profile on Windows.
  • create (bool) – If True (the default) the directory will be created if it does not exist.
class fs.appfs.UserConfigFS(appname, author=None, version=None, roaming=False, create=True)

A filesystem for per-user config data.

参数:
  • appname (str) – The name of the application.
  • author (str) – The name of the author (used on Windows).
  • version (str) – Optional version string, if a unique location per version of the application is required.
  • roaming (bool) – If True, use a roaming profile on Windows.
  • create (bool) – If True (the default) the directory will be created if it does not exist.
class fs.appfs.SiteDataFS(appname, author=None, version=None, roaming=False, create=True)

A filesystem for application site data.

参数:
  • appname (str) – The name of the application.
  • author (str) – The name of the author (used on Windows).
  • version (str) – Optional version string, if a unique location per version of the application is required.
  • roaming (bool) – If True, use a roaming profile on Windows.
  • create (bool) – If True (the default) the directory will be created if it does not exist.
class fs.appfs.SiteConfigFS(appname, author=None, version=None, roaming=False, create=True)

A filesystem for application config data.

参数:
  • appname (str) – The name of the application.
  • author (str) – The name of the author (used on Windows).
  • version (str) – Optional version string, if a unique location per version of the application is required.
  • roaming (bool) – If True, use a roaming profile on Windows.
  • create (bool) – If True (the default) the directory will be created if it does not exist.
class fs.appfs.UserCacheFS(appname, author=None, version=None, roaming=False, create=True)

A filesystem for per-user application cache data.

参数:
  • appname (str) – The name of the application.
  • author (str) – The name of the author (used on Windows).
  • version (str) – Optional version string, if a unique location per version of the application is required.
  • roaming (bool) – If True, use a roaming profile on Windows.
  • create (bool) – If True (the default) the directory will be created if it does not exist.
class fs.appfs.UserLogFS(appname, author=None, version=None, roaming=False, create=True)

A filesystem for per-user application log data.

参数:
  • appname (str) – The name of the application.
  • author (str) – The name of the author (used on Windows).
  • version (str) – Optional version string, if a unique location per version of the application is required.
  • roaming (bool) – If True, use a roaming profile on Windows.
  • create (bool) – If True (the default) the directory will be created if it does not exist.

FTP 文件系统

管理FTP服务器上的资源。

class fs.ftpfs.FTPFS(host, user='anonymous', passwd='', acct='', timeout=10, port=21)

A FTP (File Transport Protocol) Filesystem.

参数:
  • host (str) – A FTP host, e.g. 'ftp.mirror.nl'.
  • user (str) – A username (default is 'anonymous')
  • passwd – Password for the server, or None for anon.
  • acct – FTP account.
  • timeout (int) – Timeout for contacting server (in seconds).
  • port (int) – Port number (default 21).
features

Get features dict from FTP server.

内存文件系统

创建和管理内存文件系统。

class fs.memoryfs.MemoryFS

A filesystem that stores all file and directory information in memory. This makes them very fast, but non-permanent.

Memory filesystems are useful for caches, temporary data stores, unit testing, etc.

Memory filesystems require no parameters to their constructor. The following is how you would create a MemoryFS instance:

mem_fs = MemoryFS()

Mount 文件系统

MountFS 是一个 虚拟 文件系统，可以无缝地将子目录映射到其他文件系统。

例如，我们有两个文件系统分别包含配置文件和资源:

[config_fs]
|-- config.cfg
`-- defaults.cfg

[resources_fs]
|-- images
|   |-- logo.jpg
|   `-- photo.jpg
`-- data.dat

我们可以将这些文件系统合并到单个文件系统中，使用以下代码:

from fs.mountfs import MountFS
combined_fs = MountFS()
combined_fs.mount('config', config_fs)
combined_fs.mount('resources', resources_fs)

这将创建一个文件系统，其中 config/ 映射到 config_fs 的路径和 resources/ 映射到 resources_fs 的路径:

[combined_fs]
|-- config
|   |-- config.cfg
|   `-- defaults.cfg
`-- resources
    |-- images
    |   |-- logo.jpg
    |   `-- photo.jpg
    `-- data.dat

现在两个文件系统可以使用相同的路径结构访问:

print(combined_fs.gettext('/config/defaults.cfg'))
read_jpg(combined_fs.open('/resources/images/logo.jpg', 'rb')
exception fs.mountfs.MountError

Thrown when mounts conflict.

class fs.mountfs.MountFS(auto_close=True)

A virtual filesystem that maps directories on to other file-systems.

参数:auto_close (bool) – If True, the child filesystems will be closed when the MountFS is closed.
mount(path, fs)

Mounts a host FS object on a given path.

参数:
  • path (str) – A path within the MountFS.
  • fs (FS) – A filesystem object to mount.

多文件系统

MultiFS是由一系列其他文件系统组成的文件系统，其中每个文件系统的目录结构覆盖序列中的先前文件系统。

这种文件系统的一个用途是选择性地覆盖一组文件，满足自定义的功能。 例如，创建一个可用于Web应用程序 theme 的文件系统。 我们从以下目录开始:

`-- templates
    |-- snippets
    |   `-- panel.html
    |-- index.html
    |-- profile.html
    `-- base.html

`-- theme
    |-- snippets
    |   |-- widget.html
    |   `-- extra.html
    |-- index.html
    `-- theme.html

我们想创建一个单独的文件系统，只有在 theme/ 中没有找到时，才会从 templates/ 加载一个文件。 我们可以这样做:

from fs.osfs import OSFS
from fs.multifs import MultiFS

theme_fs = MultiFS()
theme_fs.add_fs('templates', OSFS('templates'))
theme_fs.add_fs('theme', OSFS('theme'))

现在我们有一个 theme_fs 文件系统，它提供了两个目录的单一视图:

|-- snippets
|   |-- panel.html
|   |-- widget.html
|   `-- extra.html
|-- index.html
|-- profile.html
|-- base.html
`-- theme.html
class fs.multifs.MultiFS(auto_close=True)

A filesystem that delegates to a sequence of other filesystems.

Operations on the MultiFS will try each ‘child’ filesystem in order, until it succeeds. In effect, creating a filesystem that combines the files and dirs of its children.

add_fs(name, fs, write=False, priority=0)

Adds a filesystem to the MultiFS.

参数:
  • name (str) – A unique name to refer to the filesystem being added.
  • fs (Filesystem) – The filesystem to add
  • write (bool) – If this value is True, then the fs will be used as the writeable FS.
  • priority (int) – An integer that denotes the priority of the filesystem being added. Filesystems will be searched in descending priority order and then by the reverse order they were added. So by default, the most recently added filesystem will be looked at first.
get_fs(name)

Get a filesystem from its name.

参数:name (str) – The name of a filesystem previously added.
iterate_fs()

Get iterator that returns (name, fs) in priority order.

which(path, mode='r')

Get a tuple of (name, filesystem) that the given path would map to.

参数:
  • path (str) – A path on the filesystem.
  • mode (str) – A open mode.

操作系统文件系统

管理操作系统提供的文件系统。

本质上， OSFS 是Python库中的 io 和 os 模块的一个兼容层。

class fs.osfs.OSFS(root_path, create=False, create_mode=511, encoding=None)

Create an OSFS.

参数:
  • root_path (str) – An OS path to the location on your HD you wish to manage.
  • create (bool) – Set to True to create the root directory if it does not already exist, otherwise the directory should exist prior to creating the OSFS instance.
  • create_mode (int) – The permissions that will be used to create the directory if create is True and the path doesn’t exist, defaults to 0o777.
  • encoding (str) – The encoding to use for paths, or None (default) to auto-detect.
引发:

fs.errors.CreateFailed – If root_path does not exists, or could not be created.

Here are some examples of creating OSFS objects:

current_directory_fs = OSFS('.')
home_fs = OSFS('~/')
windows_system32_fs = OSFS('c://system32')

子文件系统

A SubFS represents a directory in a ‘parent’ filesystem.

class fs.subfs.SubFS(parent_fs, path)

A sub-directory on another filesystem.

A SubFS is a filesystem object that maps to a sub-directory of another filesystem. This is the object that is returned by opendir().

Tar 文件系统

.tar文件的文件系统实现

class fs.tarfs.ReadTarFS(file, encoding='utf-8')

A readable tar file.

class fs.tarfs.TarFS(wrap_fs)

Read and write tar files.

There are two ways to open a TarFS for the use cases of reading a tar file, and creating a new one.

If you open the TarFS with write set to False (the default), then the filesystem will be a read only filesystem which maps to the files and directories within the tar file. Files are decompressed on the fly when you open them.

Here’s how you might extract and print a readme from a tar file:

with TarFS('foo.tar.gz') as tar_fs:
    readme = tar_fs.gettext('readme.txt')

If you open the TarFS with write set to True, then the TarFS will be a empty temporary filesystem. Any files / directories you create in the TarFS will be written in to a tar file when the TarFS is closed. The compression is set from the new file name but may be set manually with the compression argument.

Here’s how you might write a new tar file containing a readme.txt file:

with TarFS('foo.tar.xz', write=True) as new_tar:
    new_tar.settext(
        'readme.txt',
        'This tar file was written by PyFilesystem'
    )
参数:
  • file (str or file) – An OS filename, or a open file object.
  • write (bool) – Set to True to write a new tar file, or False to read an existing tar file.
  • compression (str) – Compression to use (one of the formats supported by tarfile: xz, gz, bz2, or None).
  • temp_fs (str) – An opener string for the temporary filesystem used to store data prior to tarring.
class fs.tarfs.WriteTarFS(file, compression=None, encoding='utf-8', temp_fs='temp://__tartemp__')

A writable tar file.

write_tar(file=None, compression=None, encoding=None)

Write tar to a file.

注解

This is called automatically when the TarFS is closed.

参数:
  • file (str or file-like) – Destination file, may be a file name or an open file object.
  • compression – Compression to use (one of the constants defined in the tarfile module in the stdlib).

临时文件系统

临时文件系统存储在您的操作系统定义的位置（linux上的``/ tmp``）。 当文件系统关闭时，内容被删除。

TempFS是提前准备目录结构的好方法，以便以后复制。它也可以用作临时数据存储。

class fs.tempfs.TempFS(identifier=None, temp_dir=None, auto_clean=True, ignore_clean_errors=True)

Create a temporary filesystem.

参数:
  • identifier (str) – A string to distinguish the directory within the OS temp location, used as part of the directory name.
  • temp_dir (str) – An OS path to your temp directory (leave as None to auto-detect)
  • auto_clean (bool) – If True, the directory contents will be wiped on close.
  • ignore_clean_errors (bool) – If True, any errors in the clean process will be raised. If False, they will be suppressed.
clean()

Clean (delete) temporary files created by this filesystem.

实现文件系统

有一点小心，你可以为任何文件系统实现一个PyFilesystem接口，这将允许它与任何内置的FS类和工具互换工作。

要创建一个PyFilesystem接口，从 FS 派生一个类，并实现：ref：essential-methods。这应该给你一个工作的FS类。

注意复制方法签名，包括默认值。还必须遵循关于异常的相同逻辑，并且只在以下内容中引发异常 errors 。

构造函数

对于如何构造PyFilesystem类没有特别的要求，但是一定要调用没有参数的基类 __init__ 方法。

线程安全

所有文件系统应该是 线程安全 。实现它的最简单的方法是使用 _lock 属性，它由 FS 构造函数提供。这是一个来自标准库的 RLock 对象，可以用作上下文管理器，因此实现的方法将启动如下:

with self._lock:
    do_something()

你不是 必需 使用 _lock 。只要在多线程的FS对象上调用方法不会破坏任何东西。

Python版本

PyFilesystem支持Python2.7和Python3.X。 两个主要Python版本之间的差异主要由 six 库管理。

在编写新的FS类时，您没有义务支持PyFilesystem的相同版本的Python，但是如果您的项目是一般使用的，则建议使用。

测试文件系统

要测试您的实现，可以借用用于测试内置文件系统的测试套件。如果你的代码通过这些测试，那么你可以相信你的实现将无缝工作。

这里是测试一个名为 MyFS 的文件系统类的最简单的例子:

from fs.test import FSTestCases

class TestMyFS(FSTestCases):

    def make_fs(self):
        # Return an instance of your FS object here
        return MyFS()

您可能还想覆盖测试套件中的一些方法以进行更有针对性的测试:

class fs.test.FSTestCases

Basic FS tests.

assert_bytes(path, contents)

Assert a file contains the given bytes.

参数:
  • path (str) – A path on the filesystem.
  • contents (bytes) – Bytes to compare.
assert_exists(path)

Assert a path exists.

参数:path (str) – A path on the filesystem.
assert_isdir(path)

Assert a path is a directory.

参数:path (str) – A path on the filesystem.
assert_isfile(path)

Assert a path is a file.

参数:path (str) – A path on the filesystem.
assert_not_exists(path)

Assert a path does not exist.

参数:path (str) – A path on the filesystem.
assert_text(path, contents)

Assert a file contains the given text.

参数:
  • path (str) – A path on the filesystem.
  • contents (str) – Text to compare.
destroy_fs(fs)

Destroy a FS object.

参数:fs – A FS instance previously opened by ~fs.test.FSTestCases.make_fs.
make_fs()

Return an FS instance.

基本方法

以下方法必须在PyFilesystem接口中实现。

非基本方法

以下方法可以在PyFilesystem接口中实现。

这些方法在基类中具有默认实现，但是如果您可以提供更优化的版本，则可以覆盖这些方法。

应该实现哪些方法取决于数据的存储方式和位置。 对于网络文件系统，一个好的候选实现，是 scandir 方法，否则为每个文件调用 listdir 和 getinfo 的组合。

在一般情况下，最好看看这些方法是如何实现的 FS ，并且只写一个自定义版本，如果它比默认的更有效率。

辅助方法

这些方法不应该实现。

实现这些可能不太值得的。

参考

fs.base.FS

文件系统基类对所有文件系统都是公用的。 如果你熟悉这个（相当简单）API，你可以使用任何支持的文件系统

class fs.base.FS

Base class for FS objects.

appendbytes(path, data)

Append bytes to the end of a file. Creating the file if it doesn’t already exists.

参数:
  • path (str) – Path to a file.
  • data (bytes) – Bytes to append.
Raises:

ValueError if data is not bytes.
Raises:

fs.errors.ResourceNotFound if a parent directory of path does not exist.
appendtext(path, text, encoding='utf-8', errors=None, newline='')

Append text to a file. Creating the file if it doesn’t already exists.

参数:
  • path (str) – Path to a file.
  • text (str) – Text to append.
Raises:

ValueError if text is not bytes.
Raises:

fs.errors.ResourceNotFound if a parent directory of path does not exist.
check()

Check a filesystem may be used.

Will throw a FilesystemClosed if the
filesystem is closed.
返回:None
Raises:FilesystemClosed if the filesystem is closed.
close()

Close the filesystem and release any resources.

It is important to call this method when you have finished working with the filesystem. Some filesystems may not finalize changes until they are closed (archives for example). You may call this method explicitly (it is safe to call close multiple times), or you can use the filesystem as a context manager to automatically close.

Here’s an example of automatically closing a filesystem:

with OSFS('~/Desktop') as desktop_fs:
    desktop_fs.settext(
        'note.txt',
        "Don't forget to tape Game of Thrones"
    )

If you attempt to use a filesystem that has been closed, a FilesystemClosed exception will be thrown.

copy(src_path, dst_path, overwrite=False)

Copy file contents from src_path to dst_path.

参数:
  • src_path (str) – Path of source file.
  • dst_path (str) – Path to destination file.
引发:
copydir(src_path, dst_path, create=False)

Copy the contents of src_path to dst_path.

参数:
  • src_path (str) – Source directory.
  • dst_path (str) – Destination directory.
  • create (bool) – If True then src_path will be created if it doesn’t already exist.
引发:

fs.errors.ResourceNotFound – If the destination directory does not exist, and create is not True.
create(path, wipe=False)

Create an empty file.

参数:
  • path (str) – Path to new file in filesystem.
  • wipe (bool) – Truncate any existing file to 0 bytes.
返回:

True if file was created, False if it already existed.
返回类型:

bool

The default behavior is to create a new file if one doesn’t already exist. If wipe == True an existing file will be truncated.

desc(path)

Return a short descriptive text regarding a path.

参数:path (str) – A path to a resource on the filesystem.
返回类型:str
exists(path)

Check if a path maps to a resource.

参数:path (str) – Path to a resource
返回类型:bool

A path exists if it maps to any resource (including a directory).

filterdir(path, files=None, dirs=None, exclude_dirs=None, exclude_files=None, namespaces=None, page=None)

Get an iterator of resource info, filtered by file patterns.

参数:
  • path (str) – A path to a directory on the filesystem.
  • files (list) – A list of unix shell-style patterns to filter file names, e.g. ['*.py'].
  • dirs (list) – A list of unix shell-style wildcards to filter directory names.
  • exclude_dirs (list) – An optional list of patterns used to exclude directories
  • exclude_files (list) – An optional list of patterns used to exclude files.
  • namespaces (list) – A list of namespaces to include in the resource information.
  • page (tuple or None) – May be a tuple of (<start>, <end>) indexes to return an iterator of a subset of the resource info, or None to iterate over the entire directory. Paging a directory scan may be necessary for very large directories.
返回:

An iterator of Info objects.
返回类型:

iterator

This method enhances scandir() with additional filtering functionality.

getbasic(path)

Get the basic resource info.

参数:path (str) – A path on the filesystem.
返回:Resource information object for path.
返回类型:Info

This method is shorthand for the following:

fs.getinfo(path, namespaces=['basic'])
getbytes(path)

Get the contents of a file as bytes.

参数:path (str) – A path to a readable file on the filesystem.
返回:file contents
返回类型:bytes
引发:fs.errors.ResourceNotFound – If path does not exist.
getdetails(path)

Get the details resource info.

参数:path (str) – A path on the filesystem.
返回:Resource information object for path.
返回类型:Info

This method is shorthand for the following:

fs.getinfo(path, namespaces=['details'])
getinfo(path, namespaces=None)

Get information regarding a resource (file or directory) on a filesystem.

参数:
  • path (str) – A path to a resource on the filesystem.
  • namespaces (list or None) – Info namespaces to query (defaults to ‘basic’).
返回:

Resource information object.
返回类型:

Info

For more information regarding resource information see 资源信息.

getmeta(namespace='standard')

Get meta information regarding a filesystem.

参数:
  • keys (list or None) – A list of keys to retrieve, or None for all keys.
  • namespace (str) – The meta namespace (default is “standard”).
返回类型:

dict

Meta information is associated with a namespace which may be specified with the namespace parameter. The default namespace, "standard", contains common information regarding the filesystem’s capabilities. Some filesystems may provide other namespaces, which expose less common, or implementation specific information. If a requested namespace is not supported by a filesystem, then an empty dictionary will be returned.

The "standard" namespace supports the following keys:

key Description
case_insensitive True if this filesystem is case sensitive.
invalid_path_chars A string containing the characters that may may not be used on this filesystem.
max_path_length Maximum number of characters permitted in a path, or None for no limit.
max_sys_path_length Maximum number of characters permitted in a sys path, or None for no limit.
network True if this filesystem requires a network.
read_only True if this filesystem is read only.
supports_rename True if this filesystem supports an os.rename operation.

注解

Meta information is constant for the lifetime of the filesystem, and may be cached.

getsize(path)

Get the size (in bytes) of a resource.

参数:path (str) – A path to a resource.
返回类型:int

The size of a file is the total number of readable bytes, which may not reflect the exact number of bytes of reserved disk space (or other storage medium).

The size of a directory is the number of bytes of overhead use to store the directory entry.

getsyspath(path)

Get an system path to a resource.

参数:path (str) – A path on the filesystem.
返回类型:str
引发:NoSysPath – If there is no corresponding system path.

A system path is one recognized by the OS, that may be used outside of PyFilesystem (in an application or a shell for example). This method will get the corresponding system path that would be referenced by path.

Not all filesystems have associated system paths. Network and memory based filesystems, for example, may not physically store data anywhere the OS knows about. It is also possible for some paths to have a system path, whereas others don’t.

If path doesn’t have a system path, a NoSysPath exception will be thrown.

注解

A filesystem may return a system path even if no resource is referenced by that path – as long as it can be certain what that system path would be.

gettext(path, encoding=None, errors=None, newline='')

Get the contents of a file as a string.

参数:
  • path (str) – A path to a readable file on the filesystem.
  • encoding (str) – Encoding to use when reading contents in text mode.
  • errors (str) – Unicode errors parameter.
  • newline (str) – Newlines parameter.
返回:

file contents.
引发:

fs.errors.ResourceNotFound – If path does not exist.
gettype(path)

Get the type of a resource.

参数:path – A path in the filesystem.
返回:ResourceType

A type of a resource is an integer that identifies the what the resource references. The standard type integers may be one of the values in the ResourceType enumerations.

The most common resource types, supported by virtually all filesystems are directory (1) and file (2), but the following types are also possible:

ResourceType value
unknown 0
directory 1
file 2
character 3
block_special_file 4
fifo 5
socket 6
symlink 7

Standard resource types are positive integers, negative values are reserved for implementation specific resource types.

geturl(path, purpose='download')

Get a URL to the given resource.

参数:
  • path (str) – A path on the filesystem
  • purpose (str) – A short string that indicates which URL to retrieve for the given path (if there is more than one). The default is ‘download’, which should return a URL that serves the file. Other filesystems may support other values for purpose.
返回:

A URL.
返回类型:

str
引发:

fs.errors.NoURL – If the path does not map to a URL.
hassyspath(path)

Check if a path maps to a system path.

参数:path (str) – A path on the filesystem
返回类型:bool
hasurl(path, purpose='download')

Check if a path has a corresponding URL.

参数:
  • path (str) – A path on the filesystem
  • purpose (str) – A purpose parameter, as given in geturl().
返回类型:

bool
isclosed()

Check if the filesystem is closed.

isdir(path)

Check a path exists and is a directory.

isempty(path)

Check if a directory is empty (contains no files or directories).

参数:path (str) – A directory path.
返回类型:bool
isfile(path)

Check a path exists and is a file.

listdir(path)

Get a list of the resource names in a directory.

参数:

path (str) – A path to a directory on the filesystem.
返回:

list of names, relative to path.
返回类型:

list
引发:

This method will return a list of the resources in a directory. A ‘resource’ is a file, directory, or one of the other types defined in ResourceType.

lock()

Get a context manager that locks the filesystem.

Locking a filesystem gives a thread exclusive access to it. Other threads will block until the threads with the lock has left the context manager. Here’s how you would use it:

with my_fs.lock():  # May block
    # code here has exclusive access to the filesystem

It is a good idea to put a lock around any operations that you would like to be atomic. For instance if you are copying files, and you don’t want another thread to delete or modify anything while the copy is in progress.

Locking with this method is only required for code that calls multiple filesystem methods. Individual methods are thread safe already, and don’t need to be locked.

..note ::
This only locks at the Python level. There is nothing to prevent other processes from modifying the filesystem outside of the filesystem instance.
makedir(path, permissions=None, recreate=False)

Make a directory, and return a SubFS for the new directory.

参数:
  • path (str) – Path to directory from root.
  • permissions (Permissions) – Permissions instance.
  • recreate (bool) – Do not raise an error if the directory exists.
返回类型:

SubFS
引发:
makedirs(path, permissions=None, recreate=False)

Make a directory, and any missing intermediate directories.

参数:
  • path (str) – Path to directory from root.
  • recreate (bool) – If False (default), it is an error to attempt to create a directory that already exists. Set to True to allow directories to be re-created without errors.
  • permissions – Initial permissions.
返回:

A sub-directory filesystem.
返回类型:

SubFS
引发:
match(patterns, name)

Check if a name matches any of a list of wildcards.

参数:
  • patterns (list) – A list of patterns, e.g. ['*.py']
  • name (str) – A file or directory name (not a path)
返回类型:

bool

If a filesystem is case insensitive (such as Windows) then this method will perform a case insensitive match (i.e. *.py will match the same names as *.PY). Otherwise the match will be case sensitive (*.py and *.PY will match different names).

>>> home_fs.match(['*.py'], '__init__.py')
True
>>> home_fs.match(['*.jpg', '*.png'], 'foo.gif')
False

If patterns is None, or (['*']), then this method will always return True.

move(src_path, dst_path, overwrite=False)

Move a file from src_path to dst_path.

参数:
  • src_path (str) – A path on the filesystem to move.
  • dst_path (str) – A path on the filesystem where the source file will be written to.
  • overwrite (bool) – If True destination path will be overwritten if it exists.
引发:
movedir(src_path, dst_path, create=False)

Move contents of directory src_path to dst_path.

参数:
  • src_path (str) – Path to source directory on the filesystem.
  • dst_path (str) – Path to destination directory.
  • create (bool) – If True, then dst_path will be created if it doesn’t already exist.
open(path, mode='r', buffering=-1, encoding=None, errors=None, newline='', **options)

Open a file.

参数:
  • path (str) – A path to a file on the filesystem.
  • mode (str) – Mode to open file object.
  • buffering (int) – Buffering policy: 0 to switch buffering off, 1 to select line buffering, >1 to select a fixed-size buffer, -1 to auto-detect.
  • encoding (str) – Encoding for text files (defaults to utf-8)
  • errors (str) – What to do with unicode decode errors (see stdlib docs)
  • newline (str) –

    New line parameter (See stdlib docs)

  • options – Additional keyword parameters to set implementation specific options (if required). See implementation docs for details.
返回类型:

file object
openbin(path, mode='r', buffering=-1, **options)

Open a binary file-like object.

参数:
  • path (str) – A path on the filesystem.
  • mode (str) – Mode to open file (must be a valid non-text mode). Since this method only opens binary files, the b in the mode string is implied.
  • buffering (int) – Buffering policy (-1 to use default buffering, 0 to disable buffering, or positive integer to indicate buffer size).
  • options – Keyword parameters for any additional information required by the filesystem (if any).
返回类型:

file object
引发:
opendir(path)

Get a filesystem object for a sub-directory.

参数:path (str) – Path to a directory on the filesystem.
返回:A filesystem object representing a sub-directory.
返回类型:SubFS
引发:fs.errors.DirectoryExpected – If dst_path does not exist or is not a directory.
remove(path)

Remove a file.

参数:

path (str) – Path to the file you want to remove.
引发:
removedir(path)

Remove a directory from the filesystem.

参数:

path (str) – Path of the directory to remove.
引发:
removetree(dir_path)

Recursively remove the contents of a directory.

This method is similar to removedir(), but will remove the contents of the directory if it is not empty.

参数:dir_path (str) – Path to a directory on the filesystem.
scandir(path, namespaces=None, page=None)

Get an iterator of resource info.

参数:
  • path (str) – A path on the filesystem
  • namespaces (list) – A sequence of info namespaces.
  • page (tuple or None) – May be a tuple of (<start>, <end>) indexes to return an iterator of a subset of the resource info, or None to iterator the entire directory. Paging a directory scan may be necessary for very large directories.
返回类型:

iterator
setbinfile(path, file)

Set a file to the contents of a binary file object.

参数:
  • path (str) – A path on the filesystem.
  • file (file object) – A file object open for reading in binary mode.

This method copies bytes from an open binary file to a file on the filesystem. If the destination exists, it will first be truncated.

Note that the file object file will not be closed by this method. Take care to close it after this method completes (ideally with a context manager). For example:

with open('myfile.bin') as read_file:
    my_fs.setbinfile('myfile.bin', read_file)
setbytes(path, contents)

Copy (bytes) data to a file.

参数:
  • path (str) – Destination path on the filesystem.
  • contents (bytes) – A bytes object with data to be written
setfile(path, file, encoding=None, errors=None, newline=None)

Set a file to the contents of a file object.

参数:
  • path (str) – A path on the filesystem.
  • file (file object) – A file object open for reading.
  • encoding (str) – Encoding of destination file, or None for binary.
  • errors (str) – How encoding errors should be treated (same as io.open).
  • newline (str) – Newline parameter (same is io.open).

This method will read the contents of a supplied file object, and write to a file on the filesystem. If the destination exists, it will first be truncated.

If encoding is supplied, the destination will be opened in text mode.

Note that the file object file will not be closed by this method. Take care to close it after this method completes (ideally with a context manager). For example:

with open('myfile.bin') as read_file:
    my_fs.setfile('myfile.bin', read_file)
setinfo(path, info)

Set info on a resource.

参数:
  • path (str) – Path to a resource on the filesystem.
  • info (dict) – Dict of resource info.
引发:

fs.errors.ResourceNotFound – If path does not exist on the filesystem.

This method is the compliment to getinfo and is used to set info values on a resource.

The info dict should be in the same format as the raw info returned by getinfo(file).raw. Here’s an example:

details_info = {
    "details":
    {
        "modified_time": time.time()
    }
}
my_fs.setinfo('file.txt', details_info)
settext(path, contents, encoding='utf-8', errors=None, newline='')

Create or replace a file with text.

参数:
  • contents (str) – Path on the filesystem.
  • encoding (str) – Encoding of destination file (default ‘UTF-8).
  • errors (str) – Error parameter for encoding (same as io.open).
  • newline (str) – Newline parameter for encoding (same as io.open).
settimes(path, accessed=None, modified=None)

Set the accessed and modified time on a resource.

参数:
  • accessed – The accessed time, as a datetime, or None to use the current rime.
  • modified – The modified time, or None (the default) to use the same time as accessed parameter.
touch(path)

Create a new file if path doesn’t exist, or update accessed and modified times if the path does exist.

This method is similar to the linux command of the same name.

参数:path (str) – A path to a file on the filesystem.
tree(**kwargs)

Render a tree view of the filesystem to stdout or a file.

The parameters are passed to render().

validatepath(path)

Check if a path is valid on this filesystem, and return a normalized absolute path.

Many filesystems have restrictions on the format of paths they support. This method will check that path is valid on the underlaying storage mechanism and throw a InvalidPath exception if it is not.

参数:path (str) – A path
返回:A normalized, absolute path.
Rtype str:
引发:fs.errors.InvalidPath – If the path is invalid.
Raises:FilesystemClosed if the filesystem is closed.
walk

Get a BoundWalker object for this filesystem.

fs.compress

This module can compress the contents of a filesystem.

Currently only the Zip format is supported.

fs.compress.write_tar(src_fs, file, compression=None, encoding='utf-8', walker=None)

Write the contents of a filesystem to a zip file.

参数:
  • file (str or file-like.) – Destination file, may be a file name or an open file object.
  • compression (str) – Compression to use.
  • encoding (str) – The encoding to use for filenames. The default is "utf-8".
  • walker (Walker or None) – A Walker instance, or None to use default walker. You can use this to specify which files you want to compress.
fs.compress.write_zip(src_fs, file, compression=8, encoding='utf-8', walker=None)

Write the contents of a filesystem to a zip file.

参数:
  • file (str or file-like.) – Destination file, may be a file name or an open file object.
  • compression (str) – Compression to use (one of the constants defined in the zipfile module in the stdlib).
  • encoding (str) – The encoding to use for filenames. The default is "utf-8", use "CP437" if compatibility with WinZip is desired.
  • walker (Walker or None) – A Walker instance, or None to use default walker. You can use this to specify which files you want to compress.

fs.copy

将文件从一个文件系统复制到另一个文件系统。

Functions for copying resources between filesystem.

fs.copy.copy_dir(src_fs, src_path, dst_fs, dst_path, walker=None)

Copy a directory from one filesystem to another.

参数:
  • src_fs (FS URL or instance) – Source filesystem.
  • src_path (str) – A path to a directory on src_fs.
  • dst_fs (FS URL or instance) – Destination filesystem.
  • dst_path (str) – A path to a directory on dst_fs.
  • walker (Walker) – A walker object that will be used to scan for files in src_fs. Set this if you only want to consider a sub-set of the resources in src_fs.
fs.copy.copy_file(src_fs, src_path, dst_fs, dst_path)

Copy a file from one filesystem to another.

If the destination exists, and is a file, it will be first truncated.

参数:
  • src_fs (FS URL or instance) – Source filesystem.
  • src_path (str) – Path to a file on src_fs.
  • dst_fs (FS URL or instance) – Destination filesystem.
  • dst_path (str) – Path to a file on dst_fs.
fs.copy.copy_fs(src_fs, dst_fs, walker=None)

Copy the contents of one filesystem to another.

参数:
  • src_fs – Source filesystem.
  • src_path (str) – A path to a directory on src_fs.
  • dst_fs (FS URL or instance) – Destination filesystem.
  • walker (Walker) – A walker object that will be used to scan for files in src_fs. Set this if you only want to consider a sub-set of the resources in src_fs.
fs.copy.copy_structure(src_fs, dst_fs, walker=None)

Copy directories (but not files) from src_fs to dst_fs.

参数:
  • src_fs (FS URL or instance) – Source filesystem.
  • dst_fs (FS URL or instance) – Destination filesystem.
  • walker (Walker) – A walker object that will be used to scan for files in src_fs. Set this if you only want to consider a sub-set of the resources in src_fs.

fs.enums

class fs.ResourceType

Resource Types.

Positive values are reserved, negative values are implementation dependent.

Most filesystems will support only directory(1) and file(2). Other types exist to identify more exotic resource types supported by Linux filesystems.

class fs.Seek

Constants used by file.seek.

These match os.SEEK_CUR, os.SEEK_END, and os.SEEK_SET from the standard library.

fs.errors

Defines the Exception classes thrown by PyFilesystem objects.

Errors relating to the underlying filesystem are translated in to one of the following exceptions.

All Exception classes are derived from FSError which may be used as a catch-all filesystem exception.

exception fs.errors.CreateFailed(msg=None)

An exception thrown when a FS could not be created.

exception fs.errors.DestinationExists(path, exc=None, msg=None)

Exception raised when a target destination already exists.

exception fs.errors.DirectoryExists(path, exc=None, msg=None)

Exception raised when trying to make a directory that already exists.

exception fs.errors.DirectoryExpected(path, exc=None, msg=None)

Exception raises when a directory was expected.

exception fs.errors.DirectoryNotEmpty(path, exc=None, msg=None)

Exception raised when a directory to be removed is not empty.

exception fs.errors.FileExists(path, exc=None, msg=None)

Exception raises when opening a file in exclusive mode.

exception fs.errors.FileExpected(path, exc=None, msg=None)

Exception raises when a file was expected.

exception fs.errors.FilesystemClosed(msg=None)

An exception thrown when attempting to use a closed filesystem.

exception fs.errors.FSError(msg=None)

Base exception class for the FS module.

exception fs.errors.IllegalBackReference(path)

Exception raised when too many backrefs exist in a path.

This error will occur if the back references in a path would be outside of the root. For example, "/foo/../../", contains two back references which would reference a directory above the root.

注解

This exception is a subclass of ValueError as it is not strictly speaking an issue with a filesystem or resource.

exception fs.errors.InsufficientStorage(path=None, exc=None, msg=None)

Exception raised when operations encounter storage space trouble.

exception fs.errors.InvalidCharsInPath(path, msg=None)

The path contains characters that are invalid on this filesystem.

exception fs.errors.InvalidPath(path, msg=None)

Base exception for fs paths that can’t be mapped on to the underlaying filesystem.

exception fs.errors.NoURL(path, purpose, msg=None)

Raised when there is no URL for a given path.

exception fs.errors.OperationFailed(path=None, exc=None, msg=None)

Base exception class for errors associated with a specific operation.

exception fs.errors.OperationTimeout(path=None, exc=None, msg=None)

Filesystem took too long.

exception fs.errors.PathError(path, msg=None)

Exception for errors to do with a path string.

exception fs.errors.PermissionDenied(path=None, exc=None, msg=None)

Permissions error.

exception fs.errors.RemoteConnectionError(path=None, exc=None, msg=None)

Exception raised when operations encounter remote connection trouble.

exception fs.errors.ResourceError(path, exc=None, msg=None)

Base exception class for error associated with a specific resource.

exception fs.errors.ResourceInvalid(path, exc=None, msg=None)

Exception raised when a resource is the wrong type.

exception fs.errors.ResourceLocked(path, exc=None, msg=None)

Exception raised when a resource can’t be used because it is locked.

exception fs.errors.ResourceNotFound(path, exc=None, msg=None)

Exception raised when a required resource is not found.

exception fs.errors.Unsupported(path=None, exc=None, msg=None)

Exception raised for operations that are not supported by the FS.

fs.info

class fs.info.Info(raw_info, to_datetime=<function epoch_to_datetime>)

Container for 资源信息, returned by the following methods:

参数:
  • raw_info (dict) – A dict containing resource info.
  • to_datetime – A callable that converts an epoch time to a datetime object. The default uses epoch_to_datetime().
accessed

Get the time this resource was last accessed, or None if not available.

Requires the "details" namespace.

返回类型:datetime
copy(to_datetime=None)

Create a copy of this resource info object.

created

Get the time this resource was created, or None if not available.

Requires the "details" namespace.

返回类型:datetime
get(namespace, key, default=None)

Get a raw info value.

>>> info.get('access', 'permissions')
['u_r', 'u_w', '_wx']
参数:
  • namespace (str) – A namespace identifier.
  • key (str) – A key within the namespace.
  • default – A default value to return if either the namespace or namespace + key is not found.
gid

Get the group id of a resource, or None if not available.

Requires the "access" namespace.

返回类型:int
group

Get the group of the resource owner, or None if not available.

Requires the "access" namespace.

返回类型:str
has_namespace(namespace)

Check if the resource info contains a given namespace.

参数:namespace (str) – A namespace name.
返回类型:bool
is_dir

Check if the resource references a directory.

返回类型:bool
is_file

Check if a resource references a file.

返回类型:bool
is_writeable(namespace, key)

Check if a given key in a namespace is writable (with setinfo()).

参数:
  • namespace (str) – A namespace identifier.
  • key (str) – A key within the namespace.
返回类型:

bool
make_path(dir_path)

Make a path by joining dir_path with the resource name.

参数:dir_path (str) – A path to a directory.
返回:A path.
返回类型:str
metadata_changed

Get the time the metadata changed, or None if not available.

Requires the "details" namespace.

返回类型:datetime
modified

Get the time the resource was modified, or None if not available.

Requires the "details" namespace.

返回类型:datetime
name

Get the resource name.

返回类型:str
permissions

Get a permissions object, or None if not available.

Requires the "access" namespace.

返回类型:fspermissions.Permissions
size

Get the size of the resource, in bytes.

Requires the "details" namespace.

返回类型:int
type

Get the resource type enumeration.

Requires the "details" namespace.

Type:ResourceType
uid

Get the user id of a resource, or None if not available.

Requires the "access" namespace.

返回类型:int
user

Get the owner of a resource, or None if not available.

Requires the "access" namespace.

返回类型:str

fs.move

将文件从一个文件系统移动到另一个文件系统。

Functions for moving files between filesystems.

fs.move.move_dir(src_fs, src_path, dst_fs, dst_path)

Move a directory from one filesystem to another.

参数:
  • src_fs (FS URL or instance) – Source filesystem.
  • src_path (str) – A path to a directory on src_fs.
  • dst_fs (FS URL or instance) – Destination filesystem.
  • dst_path (str) – A path to a directory on dst_fs.
fs.move.move_file(src_fs, src_path, dst_fs, dst_path)

Move a file from one filesystem to another.

参数:
  • src_fs (FS URL or instance) – Source filesystem.
  • src_path (str) – Path to a file on src_fs.
  • dst_fs (str) – Destination filesystem.
  • dst_fs – Path to a file on dst_fs.
fs.move.move_fs(src_fs, dst_fs)

Move the contents of a filesystem to another filesystem.

参数:
  • src_fs (FS URL or instance) – Source filesystem.
  • dst_fs (FS URL or instance) – Destination filesystem.

fs.mode

Tools for managing mode strings (as used in open() and openbin()).

class fs.mode.Mode(mode)

A mode object provides properties that can be used to interrogate the mode strings used when opening files.

参数:mode (str) – A mode string, as used by io.open.
引发:ValueError – If the mode string is invalid.

Here’s an example of typical use:

>>> mode = Mode('rb')
>>> mode.reading
True
>>> mode.writing
False
>>> mode.binary
True
>>> mode.text
False
appending

Check if a mode permits appending.

binary

Check if a mode specifies binary.

create

Check if the mode would create a file.

exclusive

Check if the mode require exclusive creation.

reading

Check if the mode permits reading.

text

Check if a mode specifies text.

to_platform()

Get a mode string for the current platform.

Currently, this just removes the ‘x’ on PY2 because PY2 doesn’t support exclusive mode.

to_platform_bin()

Get a binary mode string for the current platform.

Currently, this just removes the ‘x’ on PY2 because PY2 doesn’t support exclusive mode.

truncate

Check if a mode would truncate an existing file.

updating

Check if a mode permits updating (reading and writing).

validate(_valid_chars=frozenset({'x', 't', '+', 'w', 'r', 'a', 'b'}))

Validate the mode string.

引发:ValueError – if the mode contains invalid chars.
validate_bin()

Validate a mode for opening a binary file.

引发:ValueError – if the mode contains invalid chars.
writing

Check if a mode permits writing.

fs.mode.check_readable(mode)

Check a mode string allows reading.

参数:mode (str) – A mode string, e.g. "rt"
返回类型:bool
fs.mode.check_writable(mode)

Check a mode string allows writing.

参数:mode (str) – A mode string, e.g. "wt"
返回类型:bool
fs.mode.validate_open_mode(mode)

Check mode parameter of open() is valid.

参数:mode (str) – Mode parameter.
Raises:ValueError if mode is not valid.
fs.mode.validate_openbin_mode(mode, _valid_chars=frozenset({'x', '+', 'w', 'r', 'a', 'b'}))

Check mode parameter of openbin() is valid.

参数:mode (str) – Mode parameter.
Raises:ValueError if mode is not valid.

fs.opener

从URL打开文件系统

class fs.opener.Opener

The opener base class.

An opener is responsible for opening a filesystems from one or more protocols. A list of supported protocols is supplied in a class attribute called protocols.

Openers should be registered with a Registry object, which picks an appropriate opener object for a given FS URL.

open_fs(fs_url, parse_result, writeable, create, cwd)

Open a filesystem object from a FS URL.

参数:
  • fs_url (str) – A filesystem URL
  • parse_result (ParseResult) – A parsed filesystem URL.
  • writeable (bool) – True if the filesystem must be writeable.
  • create (bool) – True if the filesystem should be created if it does not exist.
  • cwd (str) – The current working directory (generally only relevant for OS filesystems).
返回:

FS object
exception fs.opener.OpenerError

Base class for opener related errors.

exception fs.opener.ParseError

Raised when attempting to parse an invalid FS URL.

class fs.opener.ParseResult(protocol, username, password, resource, path)
password

Alias for field number 2

path

Alias for field number 4

protocol

Alias for field number 0

resource

Alias for field number 3

username

Alias for field number 1

class fs.opener.Registry(default_opener='osfs')

A registry for Opener instances.

install(opener)

Install an opener.

参数:opener – An Opener instance, or a callable that returns an opener instance.

May be used as a class decorator. For example:

registry = Registry()

@registry.install
class ArchiveOpener(Opener):
    protocols = ['zip', 'tar']
open(fs_url, writeable=True, create=False, cwd='.', default_protocol='osfs')

Open a filesystem from a FS URL. Returns a tuple of a filesystem object and a path. If there is no path in the FS URL, the path value will be None.

参数:
  • fs_url (str) – A filesystem URL
  • writeable (bool) – True if the filesystem must be writeable.
  • create (bool) – True if the filesystem should be created if it does not exist.
  • cwd (str or None) – The current working directory.
返回类型:

Tuple of (<filesystem>, <path from url>)
open_fs(fs_url, writeable=True, create=False, cwd='.', default_protocol='osfs')

Open a filesystem object from a FS URL (ignoring the path component).

参数:
  • fs_url (str) – A filesystem URL
  • parse_result (ParseResult) – A parsed filesystem URL.
  • writeable (bool) – True if the filesystem must be writeable.
  • create (bool) – True if the filesystem should be created if it does not exist.
  • cwd (str) – The current working directory (generally only relevant for OS filesystems).
  • default_protocol (str) – The protocol to use if one is not supplied in the FS URL (defaults to "osfs").
返回:

FS object
exception fs.opener.Unsupported

May be raised by opener if the opener fails to open a FS.

fs.opener.manage_fs(fs_url, create=False, writeable=True, cwd='.')

A context manager opens / closes a filesystem.

参数:
  • fs_url (str or FS) – A FS instance or a FS URL.
  • create (bool) – If True, then create the filesytem if it doesn’t already exist.
  • writeable (bool) – If True, then the filesystem should be writeable.
  • cwd (str) – The current working directory, if opening a OSFS.

Sometimes it is convenient to be able to pass either a FS object or an FS URL to a function. This context manager handles the required logic for that.

Here’s an example:

def print_ls(list_fs):
    """List a directory."""
    with manage_fs(list_fs) as fs:
        print(" ".join(fs.listdir()))

This function may be used in two ways. You may either pass either a str, as follows:

print_list('zip://projects.zip')

Or, an FS instance:

from fs.osfs import OSFS
projects_fs = OSFS('~/')
print_list(projects_fs)
fs.opener.parse(fs_url)

Parse a Filesystem URL and return a ParseResult, or raise ParseError (subclass of ValueError) if the FS URL is not value.

参数:fs_url (str) – A filesystem URL
返回类型:ParseResult

fs.path

Useful functions for working with PyFilesystem paths. sdsd This is broadly similar to the standard os.path module but works with paths in the canonical format expected by all FS objects (that is, separated by forward slashes and with an optional leading slash).

See 路径 for an explanation of PyFilesystem paths.

fs.path.abspath(path)

Convert the given path to an absolute path.

Since FS objects have no concept of a current directory, this simply adds a leading / character if the path doesn’t already have one.

参数:path (str) – A PyFilesytem path.
返回:An absolute path.
返回类型:str
fs.path.basename(path)

Return the basename of the resource referenced by a path.

This is always equivalent to the ‘tail’ component of the value returned by split(path).

参数:path (str) – A PyFilesytem path.
返回类型:str 
>>> basename('foo/bar/baz')
'baz'
>>> basename('foo/bar')
'bar'
>>> basename('foo/bar/')
''
fs.path.combine(path1, path2)

Join two paths together.

参数:
  • path1 (str) – A PyFilesytem path.
  • path2 (str) – A PyFilesytem path.
返回类型:

str

This is faster than pathjoin, but only works when the second path is relative, and there are no back references in either path.

>>> combine("foo/bar", "baz")
'foo/bar/baz'
fs.path.dirname(path)

Return the parent directory of a path.

This is always equivalent to the ‘head’ component of the value returned by split(path).

参数:path (str) – A PyFilesytem path.
返回类型:str 
>>> dirname('foo/bar/baz')
'foo/bar'
>>> dirname('/foo/bar')
'/foo'
>>> dirname('/foo')
'/'
fs.path.forcedir(path)

Ensure the path ends with a trailing forward slash

参数:path – A PyFilesytem path.
返回类型:bool 
>>> forcedir("foo/bar")
'foo/bar/'
>>> forcedir("foo/bar/")
'foo/bar/'
fs.path.frombase(path1, path2)

Get the final path of path2 that isn’t in path1.

参数:
  • path1 (str) – A PyFilesytem path.
  • path2 (str) – A PyFilesytem path.
返回类型:

str

 
>>> frombase('foo/bar/', 'foo/bar/baz/egg')
'baz/egg'
fs.path.isabs(path)

Check if a path is an absolute path.

参数:path (str) – A PyFilesytem path.
返回类型:bool
fs.path.isbase(path1, path2)

Check if path1 is a base of path2.

参数:
  • path1 (str) – A PyFilesytem path.
  • path2 (str) – A PyFilesytem path.
返回类型:

bool
fs.path.isdotfile(path)

Detect if a path references a dot file, i.e. a resource who’s name starts with a ‘.’

参数:path (str) – Path to check.
返回类型:bool 
>>> isdotfile('.baz')
True
>>> isdotfile('foo/bar/.baz')
True
>>> isdotfile('foo/bar.baz')
False
fs.path.isparent(path1, path2)

Check if path1 is a parent directory of path2.

参数:
  • path1 (str) – A PyFilesytem path.
  • path2 (str) – A PyFilesytem path.
返回类型:

bool

 
>>> isparent("foo/bar", "foo/bar/spam.txt")
True
>>> isparent("foo/bar/", "foo/bar")
True
>>> isparent("foo/barry", "foo/baz/bar")
False
>>> isparent("foo/bar/baz/", "foo/baz/bar")
False
fs.path.issamedir(path1, path2)

Check if two paths reference a resource in the same directory.

参数:
  • path1 (str) – A PyFilesytem path.
  • path2 (str) – A PyFilesytem path.
返回类型:

bool

 
>>> issamedir("foo/bar/baz.txt", "foo/bar/spam.txt")
True
>>> issamedir("foo/bar/baz/txt", "spam/eggs/spam.txt")
False
fs.path.iswildcard(path)

Check if a path ends with a wildcard.

参数:path (int) – An FS path.
返回类型:bool 
>>> iswildcard('foo/bar/baz.*')
True
>>> iswildcard('foo/bar')
False
fs.path.iteratepath(path)

Iterate over the individual components of a path.

>>> iteratepath('/foo/bar/baz')
['foo', 'bar', 'baz']
参数:path (str) – Path to iterate over.
返回:A list of path components.
返回类型:list
fs.path.join(*paths)

Join any number of paths together.

参数:paths – Paths to join are given in positional arguments.
返回类型:str 
>>> pathjoin('foo', 'bar', 'baz')
'foo/bar/baz'
>>> pathjoin('foo/bar', '../baz')
'foo/baz'
>>> pathjoin('foo/bar', '/baz')
'/baz'
fs.path.normpath(path)

Normalize a path.

This function simplifies a path by collapsing back-references and removing duplicated separators.

参数:path (str) – Path to normalize.
返回:A valid FS path.
Type:str 
>>> normpath("/foo//bar/frob/../baz")
'/foo/bar/baz'
>>> normpath("foo/../../bar")
Traceback (most recent call last)
    ...
IllegalBackReference: Too many backrefs in 'foo/../../bar'
fs.path.recursepath(path, reverse=False)

Get intermediate paths from the root to the given path.

参数:
  • path (str) – A PyFilesystem path
  • reverse (bool) – Reverses the order of the paths.
返回:

A list of paths.
返回类型:

list

 
>>> recursepath('a/b/c')
['/', '/a', '/a/b', '/a/b/c']
fs.path.relativefrom(base, path)

Return a path relative from a given base path, i.e. insert backrefs as appropriate to reach the path from the base.

参数:
  • base (str) – Path to a directory.
  • path (atr) – Path you wish to make relative.
 
>>> relativefrom("foo/bar", "baz/index.html")
'../../baz/index.html'
fs.path.relpath(path)

Convert the given path to a relative path.

This is the inverse of abspath(), stripping a leading '/' from the path if it is present.

参数:path (str) – Path to adjust
返回类型:str 
>>> relpath('/a/b')
'a/b'
fs.path.split(path)

Split a path into (head, tail) pair.

This function splits a path into a pair (head, tail) where ‘tail’ is the last pathname component and ‘head’ is all preceding components.

参数:path (str) – Path to split
返回:tuple of (head, tail)
返回类型:tuple 
>>> split("foo/bar")
('foo', 'bar')
>>> split("foo/bar/baz")
('foo/bar', 'baz')
>>> split("/foo/bar/baz")
('/foo/bar', 'baz')
fs.path.splitext(path)

Split the extension from the path, and returns the path (up to the last ‘.’ and the extension).

参数:path – A path to split
返回:tuple of (path, extension)
返回类型:tuple 
>>> splitext('baz.txt')
('baz', '.txt')
>>> splitext('foo/bar/baz.txt')
('foo/bar/baz', '.txt')

fs.permissions

An abstract permissions container.

class fs.permissions.Permissions(names=None, mode=None, user=None, group=None, other=None, sticky=None, setuid=None, setguid=None)

An abstraction for file system permissions.

参数:
  • names (list) – A list of permissions.
  • mode (int) – A mode integer.
  • user (str) – A triplet of user permissions, e.g. "rwx" or "r--"
  • group (str) – A triplet of group permissions, e.g. "rwx" or "r--"
  • other (str) – A triplet of other permissions, e.g. "rwx" or "r--"
  • sticky (bool) – A boolean for the sticky bit.
  • setuid (bool) – A boolean for the setuid bit.
  • setguid (bool) – A boolean for the setuid bit.

Permissions objects store information regarding the permissions on a resource. It supports Linux permissions, but is generic enough to manage permission information from almost any filesystem.

>>> from fs.permissions import Permissions
>>> p = Permissions(user='rwx', group='rw-', other='r--')
>>> print(p)
rwxrw-r--
>>> p.mode
500
>>> oct(p.mode)
'0764'
add(*permissions)

Add permission(s).

参数:permissions – Permission name(s).
as_str()

Get a linux-style string representation of permissions.

check(*permissions)

Check if one or more permissions are enabled.

参数:permissions – Permission name(s).
返回:True if all given permissions are set.
Rtype bool:
copy()

Make a copy of this permissions object.

classmethod create(init=None)

Create a permissions object from an initial value.

参数:init – May be None for equivalent for 0o777 permissions, a mode integer, or a list of permission names.
返回:mode integer, that may be used by os.makedir (amongst others). 
>>> Permissions.create(None)
Permissions(user='rwx', group='rwx', other='rwx')
>>> Permissions.create(0o700)
Permissions(user='rwx', group='', other='')
>>> Permissions.create(['u_r', 'u_w', 'u_x'])
Permissions(user='rwx', group='', other='')
dump()

Get a list suitable for serialization.

g_r

Boolean for ‘g_r’ permission.

g_w

Boolean for ‘g_w’ permission.

g_x

Boolean for ‘g_x’ permission.

classmethod get_mode(init)

Convert an initial value to a mode integer.

classmethod load(permissions)

Load a serialized permissions object.

mode

Mode integer.

o_r

Boolean for ‘o_r’ permission.

o_w

Boolean for ‘o_w’ permission.

o_x

Boolean for ‘o_x’ permission.

classmethod parse(ls)

Parse permissions in linux notation.

remove(*permissions)

Remove permission(s).

参数:permissions – Permission name(s).
setguid

Boolean for ‘setguid’ permission.

setuid

Boolean for ‘setuid’ permission.

sticky

Boolean for ‘sticky’ permission.

u_r

Boolean for ‘u_r’ permission.

u_w

Boolean for ‘u_w’ permission.

u_x

Boolean for ‘u_x’ permission.

fs.permissions.make_mode(init)

Make a mode integer from an initial value.

fs.tools

A collection of functions that operate on filesystems and tools.

fs.tools.copy_file_data(src_file, dst_file, chunk_size=None)

Copy data from one file object to another.

参数:
  • src_file (file-like) – File open for reading.
  • dst_file (file-like) – File open for writing.
  • chunk_size (int) – Number of bytes to copy at a time (or None to use sensible default).
fs.tools.get_intermediate_dirs(fs, dir_path)

Get paths of intermediate directories required to create a new directory.

参数:
  • fs – A FS object.
  • dir_path (str) – A path to a new directory on the filesystem.
返回:

A list of paths.
返回类型:

list
引发:

fs.errors.DirectoryExpected – If a path component references a file and not a directory.
fs.tools.remove_empty(fs, path)

Remove all empty parents.

参数:
  • fs – A FS object.
  • path (str) – Path to a directory on the filesystem.

fs.tree

渲染文本树视图，在终端中使用可选颜色

Render a FS object as text tree views.

fs.tree.render(fs, path='/', file=None, encoding=None, max_levels=5, with_color=None, dirs_first=True, exclude=None, filter=None)

Render a directory structure in to a pretty tree.

参数:
  • fs (A FS instance) – A filesystem.
  • file (file or None) – An open file-like object to render the tree, or None for stdout.
  • max_levels (int) – Maximum number of levels to display, or None for no maximum.
  • with_color (bool) – Enable terminal color output, or None to auto-detect terminal.
  • dirs_first (bool) – Show directories first.
  • exclude (list) – Option list of directory patterns to exclude from the tree render.
  • filter – Optional list of files patterns to match in the tree render.
返回类型:

tuple
返回:

A tuple of (<directory count>, <file count>).

fs.walk

The machinery for walking a filesystem. See walk for details.

class fs.walk.BoundWalker(fs, walker_class=<class 'fs.walk.Walker'>)

A class that binds a Walker instance to a FS object.

参数:
  • fs – A FS object.
  • walker_class – A WalkerBase sub-class. The default uses Walker.

You will typically not need to create instances of this class explicitly. Filesystems have a walk property which returns a BoundWalker object.

>>> import fs
>>> home_fs = fs.open_fs('~/')
>>> home_fs.walk
BoundWalker(OSFS('/Users/will', encoding='utf-8'))

A BoundWalker is callable. Calling it is an alias for walk().

dirs(path='/', **kwargs)

Walk a filesystem, yielding absolute paths to directories.

参数:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
返回:

An iterable of directory paths (absolute from the FS root).

This method invokes dirs() with the bound FS object.

files(path='/', **kwargs)

Walk a filesystem, yielding absolute paths to files.

参数:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of file name patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
返回:

An iterable of file paths (absolute from the filesystem root).

This method invokes files() with the bound FS object.

info(path='/', namespaces=None, **kwargs)

Walk a filesystem, yielding tuples of (<absolute path>, <resource info>).

参数:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of file name patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
返回:

An iterable Info objects.

This method invokes info() with the bound FS object.

walk(path='/', namespaces=None, **kwargs)

Walk the directory structure of a filesystem.

参数:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of file name patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
返回:

Step iterator.

The return value is an iterator of (<path>, <dirs>, <files>) named tuples, where <path> is an absolute path to a directory, and <dirs> and <files> are a list of Info objects for directories and files in <path>.

Here’s an example:

home_fs = open_fs('~/')
walker = Walker(filter=['*.py'])
for path, dirs, files in walker.walk(home_fs, namespaces=['details']):
    print("[{}]".format(path))
    print("{} directories".format(len(dirs)))
    total = sum(info.size for info in files)
    print("{} bytes {}".format(total))

This method invokes walk() with bound FS object.

class fs.walk.Step(path, dirs, files)
dirs

Alias for field number 1

files

Alias for field number 2

path

Alias for field number 0

class fs.walk.Walker(ignore_errors=False, on_error=None, search='breadth', filter=None, exclude_dirs=None)

A walker object recursively lists directories in a filesystem.

参数:
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of filename patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk. e.g. ['*.svn', '*.git'].
classmethod bind(fs)

This binds in instance of the Walker to a given filesystem, so that you won’t need to explicitly provide the filesystem as a parameter. Here’s an example of binding:

>>> from fs import open_fs
>>> from fs.walk import Walker
>>> home_fs = open_fs('~/')
>>> walker = Walker.bind(home_fs)
>>> for path in walker.files(filter=['*.py']):
...     print(path)

Unless you have written a customized walker class, you will be unlikely to need to call this explicitly, as filesystem objects already have a walk attribute which is a bound walker object. Here’s how you might use it:

>>> from fs import open_fs
>>> home_fs = open_fs('~/')
>>> for path in home_fs.walk.files(filter=['*.py']):
...     print(path)
参数:fs – A filesystem object.
返回:a BoundWalker
check_file(fs, info)

Check if a filename should be included in the walk. Override to exclude files from the walk.

参数:
  • fs (FS) – A FS object.
  • info – A Info object.
返回类型:

bool
check_open_dir(fs, info)

Check if a directory should be opened. Override to exclude directories from the walk.

参数:
  • fs (FS) – A FS object.
  • info – A Info object.
返回类型:

bool
filter_files(fs, infos)

Filters a sequence of resource Info objects.

The default implementation filters those files for which check_file() returns True.

参数:
  • fs (FS) – A FS object.
  • infos (list) – A list of Info instances.
返回类型:

list
walk(fs, path='/', namespaces=None)

Walk the directory structure of a filesystem.

参数:
  • fs – A FS object.
  • path (str) – a path to a directory.
  • namespaces (list) – A list of additional namespaces to add to the Info objects.
返回:

Step iterator.

The return value is an iterator of (<path>, <dirs>, <files>) named tuples, where <path> is an absolute path to a directory, and <dirs> and <files> are a list of Info objects for directories and files in <path>.

Here’s an example:

home_fs = open_fs('~/')
walker = Walker(filter=['*.py'])
for path, dirs, files in walker.walk(home_fs, namespaces=['details']):
    print("[{}]".format(path))
    print("{} directories".format(len(dirs)))
    total = sum(info.size for info in files)
    print("{} bytes {}".format(total))
class fs.walk.WalkerBase

The base class for a Walker.

To create a custom walker, implement walk() in a sub-class.

See Walker() for a fully featured walker object that should be adequate for all but your most exotic directory walking needs.

dirs(fs, path='/')

Walk a filesystem, yielding absolute paths to directories.

参数:
  • fs (str) – A FS object.
  • path (str) – A path to a directory.
files(fs, path='/')

Walk a filesystem, yielding absolute paths to files.

参数:
  • fs – A FS object.
  • path (str) – A path to a directory.
返回:

An iterable of file paths.
info(fs, path='/', namespaces=None)

Walk a filesystem, yielding tuples of (<absolute path>, <resource info>).

参数:
  • fs (str) – A FS object.
  • path (str) – A path to a directory.
  • namespaces (list) – A list of additional namespaces to add to the Info objects.
返回:

An iterable of Info objects.
walk(fs, path='/', namespaces=None)

Walk the directory structure of a filesystem.

参数:
  • fs – A FS object.
  • path (str) – a path to a directory.
  • namespaces (list) – A list of additional namespaces to add to the Info objects.
返回:

Iterator of Step named tuples.

fs.wildcard

Match wildcard filenames.

fs.wildcard.get_matcher(patterns, case_sensitive)

Get a callable that checks a list of names matches the given wildcard patterns.

参数:
  • patterns (list) – A list of wildcard pattern. e.g. ["*.py", "*.pyc"]
  • case_sensitive (bool) – If True, then the callable will be case sensitive, otherwise it will be case insensitive.
返回类型:

callable

Here’s an example:

>>> import wildcard
>>> is_python = wildcard.get_macher(['*.py'])
>>> is_python('__init__.py')
>>> True
>>> is_python('foo.txt')
>>> False
fs.wildcard.imatch(pattern, name)

Test whether name matches pattern, ignoring case differences.

参数:
  • pattern (str) – A wildcard pattern. e.g. "*.py"
  • name (str) – A filename
返回类型:

bool
fs.wildcard.imatch_any(patterns, name)

Test if a name matches at least one of a list of patterns, ignoring case differences. Will return True if patterns is an empty list.

参数:
  • patterns (list) – A list of wildcard pattern. e.g. ["*.py", "*.pyc"]
  • name (str) – A filename.
返回类型:

bool
fs.wildcard.match(pattern, name)

Test whether name matches pattern.

参数:
  • pattern (str) – A wildcard pattern. e.g. "*.py"
  • name (str) – A filename
返回类型:

bool
fs.wildcard.match_any(patterns, name)

Test if a name matches at least one of a list of patterns. Will return True if patterns is an empty list.

参数:
  • patterns (list) – A list of wildcard pattern. e.g. ["*.py", "*.pyc"]
  • name (str) – A filename.
返回类型:

bool

fs.wrap

class fs.wrap.WrapCachedDir(wrap_fs)

Caches filesystem directory information.

This filesystem caches directory information retrieved from a scandir call. This may speed up code that calls isdir, isfile, or gettype too frequently.

注解

Using this wrap will prevent changes to directory information being visible to the filesystem object. Consequently it is best used only in a fairly limited scope where you don’t expected anything on the filesystem to change.

class fs.wrap.WrapReadOnly(wrap_fs)

Makes a Filesystem read-only. Any call that would would write data or modify the filesystem in any way will raise a ResourceReadOnly exception.

fs.wrap.cache_directory(fs)

Make a filesystem that caches directory information.

参数:fs – A FS object.
返回:A filesystem that caches results of scandir, isdir and other methods which read directory information.
fs.wrap.read_only(fs)

Make a read-only filesystem.

参数:fs – A FS object.
返回:A read only version of fs.

fs.wrapfs

class fs.wrapfs.WrapFS(wrap_fs)

” A proxy for a filesystem object.

This class exposes an filesystem interface, where the data is stored on another filesystem(s), and is the basis for SubFS and other virtual filesystems.

delegate_fs()

Get the filesystem.

This method should return a filesystem for methods not associated with a path, e.g. getmeta().

delegate_path(path)

Encode a path for proxied filesystem.

参数:path (str) – A path on the fileystem.
返回:a tuple of <filesystem>, <new path>
返回类型:tuple