megfile

megfile - Megvii 文件库

文档：http://megvii-research.github.io/megfile

megfile 提供了不同后端（目前包括本地文件系统和s3）的丝滑操作体验，使你能够更专注于自己项目的逻辑，而不是"这个文件使用的是哪个后端？"的问题。

megfile 提供：

几乎统一的文件系统操作体验。目标路径可以轻松从本地文件系统移动到s3。
完整的边界情况处理。即使是最困难（甚至你想不到的）边界条件，megfile 都能帮你轻松处理。
完善的类型提示和内置文档。你可以享受IDE的自动补全和静态检查。
语义化版本和升级指南，让你轻松享受最新功能。

megfile 的优势：

smart_open 可以打开使用各种协议的资源。特别是，megfile 中的s3读写器是使用多线程实现的，比已知的竞争对手更快。
smart_glob 适用于大多数协议。它支持zsh扩展模式语法的[]，例如s3://bucket/video.{mp4,avi}。
包罗万象的函数，如 smart_exists / smart_stat / smart_sync。如果你没有找到想要的功能，提交一个issue。
兼容 pathlib.Path 接口，参考 SmartPath 和其他协议类如 S3Path。

支持的协议

fs（本地文件系统）
s3
sftp
http
stdio
hdfs: pip install 'megfile[hdfs]'

快速开始

megfile 中的路径字符串几乎都是 protocol://path/to/file，例如 s3://bucketA/key。但sftp路径略有不同，格式为 sftp://[username[:password]@]hostname[:port]//file_path，相对路径将 //file_path 替换为 /file_path。以下是一个将文件写入s3 / fs，同步到本地，读取并最终删除的示例。

功能接口

from megfile import smart_open, smart_exists, smart_sync, smart_remove, smart_glob

# 在s3桶中打开一个文件
with smart_open('s3://playground/megfile-test', 'w') as fp:
    fp.write('megfile is not silver bullet')

# 测试s3桶中的文件是否存在
smart_exists('s3://playground/megfile-test')

# 或者在本地文件系统中
smart_exists('/tmp/playground/megfile-test')

# 复制文件或目录
smart_sync('s3://playground/megfile-test', '/tmp/playground/megfile-test')

# 删除文件或目录
smart_remove('s3://playground/megfile-test')

# 在s3桶中glob文件或目录
smart_glob('s3://playground/megfile-?.{mp4,avi}')

SmartPath接口

SmartPath 有一个类似于pathlib.Path的接口。

from megfile.smart_path import SmartPath

path = SmartPath('s3://playground/megfile-test')
if path.exists():
    with path.open() as f:
        result = f.read(7)
        assert result == b'megfile'

命令行接口

$ pip install 'megfile[cli]'  # 安装megfile cli要求

$ megfile --help  # 查看你可以做什么

$ megfile ls s3://playground/
$ megfile ls -l -h s3://playground/

$ megfile cat s3://playground/megfile-test

$ megfile cp s3://playground/megfile-test /tmp/playground/megfile-test

安装

PyPI

pip3 install megfile

你也可以指定megfile版本

pip3 install "megfile~=0.0"

从源代码构建

megfile可以从源代码安装

git clone git@github.com:megvii-research/megfile.git
cd megfile
pip3 install -U .

开发环境

git clone git@github.com:megvii-research/megfile.git
cd megfile
pip3 install -r requirements.txt -r requirements-dev.txt

配置

以 s3 为例，以下描述配置方法。更多详情，请参考配置。

你可以使用环境变量和配置文件进行配置，优先级是环境变量优先于配置文件。

使用环境变量

你可以使用环境变量为你的 s3 账户设置认证凭据：

AWS_ACCESS_KEY_ID：访问密钥
AWS_SECRET_ACCESS_KEY：密钥
OSS_ENDPOINT / AWS_ENDPOINT_URL_S3 / AWS_ENDPOINT_URL：s3的端点URL
AWS_S3_ADDRESSING_STYLE：寻址风格

使用命令

你可以使用 megfile 命令轻松更新配置文件： megfile config s3 [OPTIONS] AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

$ megfile config s3 accesskey secretkey

# 对于阿里云
$ megfile config s3 accesskey secretkey \
--addressing-style virtual \
--endpoint-url http://oss-cn-hangzhou.aliyuncs.com \

你可以从 ~/.aws/credentials 获取配置，如：

[default]
aws_secret_access_key = accesskey
aws_access_key_id = secretkey

s3 =
    addressing_style = virtual
    endpoint_url = http://oss-cn-hangzhou.aliyuncs.com

如何贡献

我们欢迎每个人为 megfile 项目贡献代码，但贡献的代码需要尽可能满足以下条件：

即使代码不满足条件，你也可以提交代码。项目成员将评估并协助你进行代码修改
- 代码格式：你的代码需要通过代码格式检查。megfile 使用 ruff 作为lint工具
- 静态检查：你的代码需要完整的类型提示。megfile 使用 pytype 作为静态检查工具。如果 pytype 在静态检查中失败，使用 # pytype: disable=XXX 禁用错误，并请告诉我们你为什么禁用它。
- 测试：你的代码需要完整的单元测试覆盖。megfile 在单元测试中使用 pyfakefs 和 moto 作为本地文件系统和s3虚拟环境。新增的代码应该有完整的单元测试以确保正确性
你可以通过多种方式帮助改进 megfile：
- 编写代码。
- 改进文档。
- 报告或调查bugs和issues。
- 如果你发现任何问题或有任何改进建议，也可以提交一个新的issue。我们会尽快回复并评估是否采纳。
- 审查pull requests。
- 为 megfile 仓库点星。
- 向你的朋友推荐 megfile。
- 欢迎任何其他形式的贡献。