smart_open项目版本迁移指南：从旧版本升级到新版本的最佳实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00566/article/details/148578579

smart_open项目版本迁移指南：从旧版本升级到新版本的最佳实践

smart_open Utils for streaming large files (S3, HDFS, gzip, bz2...) 项目地址: https://gitcode.com/gh_mirrors/smar/smart_open

概述

smart_open是一个功能强大的Python库，用于高效地处理各种存储系统（如本地文件系统、S3、HTTP等）中的文件读写操作。随着项目的不断演进，一些API接口和功能实现方式发生了变化。本文将详细介绍从旧版本迁移到新版本时需要注意的关键变更点，帮助开发者顺利完成升级。

压缩参数变更

从6.0.0版本开始，ignore_ext参数已被弃用，取而代之的是更直观的compression参数。

新旧参数对比

# 旧版本写法（不再支持）
fin = smart_open.open("/path/file.gz", ignore_ext=True)

# 新版本写法（禁用压缩）
fin = smart_open.open("/path/file.gz", compression="disable")

# 旧版本默认行为（不再支持）
fin = smart_open.open("/path/file.gz", ignore_ext=False)

# 新版本默认行为（自动推断压缩格式）
fin = smart_open.open("/path/file.gz")
# 或者显式指定
fin = smart_open.open("/path/file.gz", compression="infer_from_extension")

# 强制指定压缩格式（即使文件扩展名不匹配）
fin = smart_open.open("/path/file", compression=".gz")

为什么需要变更？

ignore_ext参数名称不够直观，无法清晰表达其控制压缩行为的功能。新的compression参数提供了更明确的语义：

"disable"：完全禁用压缩处理
"infer_from_extension"：根据文件扩展名自动推断（默认行为）
".gz"/".bz2"等：强制使用指定压缩格式

S3 API客户端变更

5.0.0版本对S3后端进行了重大改进，从boto3的resource API切换到了client API。

变更背景

旧版使用的resource API存在以下问题：

不是线程安全的
不支持多进程环境
随着功能增加，传输参数列表变得臃肿难维护

新版client API解决了这些问题，同时保持了功能兼容性。

废弃的参数

以下传输参数已不再支持：

multipart_upload_kwargs
object_kwargs
resource
resource_kwargs
session
singlepart_upload_kwargs

迁移指南

1. 替换session参数

旧版代码：

smart_open.open('s3://bucket/key', transport_params={'session': session})

新版代码：

smart_open.open('s3://bucket/key', transport_params={'client': session.client('s3')})

2. 替换resource参数

旧版代码：

resource = session.resource('s3', **resource_kwargs)
smart_open.open('s3://bucket/key', transport_params={'resource': resource})

新版代码：

client = session.client('s3')
smart_open.open('s3://bucket/key', transport_params={'client': client})

3. 参数映射表

旧版resource API参数需要转换为对应的client API参数：

| 旧参数名 | 对应的client API方法 | |-------------------------|--------------------------------------| | multipart_upload_kwargs | S3.Client.create_multipart_upload | | object_kwargs | S3.Client.get_object | | resource_kwargs | S3.client初始化参数 | | singlepart_upload_kwargs| S3.Client.put_object |

4. 自定义端点示例

旧版代码：

session = boto3.Session(profile_name='cloudprovider')
resource_kwargs = {'endpoint_url': 'https://region.cloudprovider.com'}
with open('s3://bucket/key.txt', 'wb', transport_params={'resource_kwarg': resource_kwargs}) as fout:
    fout.write(b'here we stand')

新版代码：

session = boto3.Session(profile_name='cloudprovider')
client = session.client('s3', endpoint_url='https://region.cloudprovider.com')
with open('s3://bucket/key.txt', 'wb', transport_params={'client': client}) as fout:
    fout.write(b'here we stand')

依赖管理变更

3.0.0版本引入了更灵活的依赖管理机制。

变更内容

旧版：安装smart_open时会自动安装所有依赖
新版：默认不安装任何存储后端的依赖，可按需安装

安装方式示例

# 仅安装AWS S3支持
pip install smart_open[s3]

# 安装所有支持（等同于旧版行为）
pip install smart_open[all]

# 安装特定组合（如S3和HTTP）
pip install smart_open[s3,http]

为什么需要变更？

随着支持的存储后端增多，一次性安装所有依赖会导致：

安装包体积过大
安装时间过长
可能引入不需要的依赖

新机制让开发者可以只安装实际需要的依赖，保持环境精简。

核心函数变更

1.8.1版本引入了新的smart_open.open函数替代旧的smart_open.smart_open。

主要改进

完全兼容Python内置open函数
默认模式改为"r"（读取文本）
参数文档更完善

迁移指南

1. 导入变更

# 旧版导入
from smart_open import smart_open

# 新版导入
from smart_open import open

2. 默认模式变更

旧版默认是二进制模式("rb")，新版改为文本模式("r")：

# 旧版（二进制模式）
smart_open.smart_open('s3://path/to/file').read(32)

# 新版（需显式指定二进制模式）
smart_open.open('s3://path/to/file', 'rb').read(32)

3. 传输参数变更

旧版直接传递参数：

smart_open.smart_open(url, 'r', session=session)

新版需要通过transport_params字典传递：

open(url, 'r', transport_params={'session': session})

4. 参数重命名

s3_upload → multipart_upload_kwargs
s3_session → session

5. 移除的参数

profile_name参数已移除，需传递完整的boto3.Session对象：

# 旧版
smart_open.smart_open(url, 'r', profile_name='myprofile')

# 新版
params = {'session': boto3.Session(profile_name='myprofile')}
open(url, 'r', transport_params=params)