文本距离

TextDistance —— 一个用于通过多种算法比较两个或多个序列之间距离的 Python 库。

特性：

• 30 多种算法
• 纯 Python 实现
• 使用简单
• 支持多于两个序列的比较
• 部分算法在一个类中提供多种实现
• 可选使用 NumPy 以获得最大速度。

算法

基于编辑距离

算法	类	函数
汉明距离	Hamming	hamming
MLIPNS	MLIPNS	mlipns
莱文斯坦距离	Levenshtein	levenshtein
达默劳-莱文斯坦距离	DamerauLevenshtein	damerau_levenshtein
贾罗-温克勒距离	JaroWinkler	jaro_winkler, jaro
Strcmp95	StrCmp95	strcmp95
尼德尔曼-温施算法	NeedlemanWunsch	needleman_wunsch
后藤算法	Gotoh	gotoh
史密斯-沃特曼算法	SmithWaterman	smith_waterman

基于标记

算法	类	函数
雅卡尔指数	Jaccard	jaccard
索伦森-戴斯系数	Sorensen	sorensen, sorensen_dice, dice
特弗斯基指数	Tversky	tversky
重叠系数	Overlap	overlap
塔尼莫托距离	Tanimoto	tanimoto
余弦相似度	Cosine	cosine
蒙格-埃尔坎	MongeElkan	monge_elkan
袋距离	Bag	bag

基于序列

算法	类	函数
最长公共子序列相似度	LCSSeq	lcsseq
最长公共子串相似度	LCSStr	lcsstr
拉特克利夫-奥伯斯赫普相似度	RatcliffObershelp	ratcliff_obershelp

基于压缩

归一化压缩距离 使用不同的压缩算法。

经典压缩算法：

算法	类	函数
算术编码	ArithNCD	arith_ncd
游程编码	RLENCD	rle_ncd
BWT 游程编码	BWTRLENCD	bwtrle_ncd

普通压缩算法：

算法	类	函数
平方根	SqrtNCD	sqrt_ncd
熵	EntropyNCD	entropy_ncd

正在进行中的算法，将两个字符串视为位数组进行比较：

算法	类	函数
BZ2	BZ2NCD	bz2_ncd
LZMA	LZMANCD	lzma_ncd
ZLib	ZLIBNCD	zlib_ncd

更多关于 NCD 的详细信息，请参阅 博客文章。

音韵学

算法	类	函数
MRA	MRA	mra
Editex	Editex	editex

简单

算法	类	函数
前缀相似度	Prefix	prefix
后缀相似度	Postfix	postfix
长度距离	Length	length
身份相似度	Identity	identity
矩阵相似度	Matrix	matrix

安装

稳定版

仅使用纯 Python 实现：

pip install textdistance

若需借助额外库以获得最佳性能：

pip install "textdistance[extras]"

若需所有依赖库（用于基准测试和运行测试）：

pip install "textdistance[benchmark]"

若仅需特定算法的扩展包：

pip install "textdistance[Hamming]"

支持扩展的算法包括：DamerauLevenshtein、Hamming、Jaro、JaroWinkler、Levenshtein。

开发版

通过 pip 安装：

pip install -e git+https://github.com/life4/textdistance.git#egg=textdistance

或者克隆仓库并安装包含部分扩展的版本：

git clone https://github.com/life4/textdistance.git
pip install -e ".[benchmark]"

使用方法

所有算法均提供两种接口：

1. 带有算法特有参数的类，用于自定义配置。
2. 具有默认参数的类实例，适合快速简便的使用场景。

所有算法都具有一些通用方法：

1. .distance(*sequences) -- 计算序列之间的距离。
2. .similarity(*sequences) -- 计算序列之间的相似度。
3. .maximum(*sequences) -- 距离与相似度的最大可能值。对于任意序列，均有 distance + similarity == maximum。
4. .normalized_distance(*sequences) -- 归一化后的序列间距离。返回值为 0 到 1 之间的浮点数，其中 0 表示完全相同，1 表示完全不同。
5. .normalized_similarity(*sequences) -- 归一化后的序列间相似度。返回值为 0 到 1 之间的浮点数，其中 0 表示完全不同，1 表示完全相同。

最常见的初始化参数：

1. qval -- 用于将序列分割成 q-gram 的 q 值。可选值：
   • 1（默认）-- 按字符比较序列。
   • 2 或更高 -- 将序列转换为 q-gram。
   • None -- 按单词分割序列。
2. as_set -- 适用于基于标记的算法：
   • True -- t 和 ttt 视为相等。
   • False（默认）-- t 和 ttt 视为不同。

示例

以 汉明距离 为例：

import textdistance

textdistance.hamming('test', 'text')
# 1

textdistance.hamming.distance('test', 'text')
# 1

textdistance.hamming.similarity('test', 'text')
# 3

textdistance.hamming.normalized_distance('test', 'text')
# 0.25

textdistance.hamming.normalized_similarity('test', 'text')
# 0.75

textdistance.Hamming(qval=2).distance('test', 'text')
# 2

其他算法也具有相同的接口。

文章

以下是一些介绍如何在实际中使用 textdistance 的文章：

• Python 模糊匹配指南
• 字符串相似度——基础算法指南！
• 归一化压缩距离

额外库

对于主要算法，textdistance 会优先尝试调用已知的外部库（按速度从快到慢排序），前提是这些库已安装在您的系统中且适用（即该实现可以处理当前类型的序列）。请通过安装带扩展的 textdistance 来启用此功能。

您也可以通过在初始化时传入 external=False 参数来禁用此功能：

import textdistance
hamming = textdistance.Hamming(external=False)
hamming('text', 'testit')
# 3

支持的库包括：

1. jellyfish
2. py_stringmatching
3. pylev
4. Levenshtein
5. pyxDamerauLevenshtein

支持的算法：

1. DamerauLevenshtein
2. Hamming
3. Jaro
4. JaroWinkler
5. Levenshtein

基准测试

未安装扩展时的结果如下：

算法	库	时间
DamerauLevenshtein	rapidfuzz	0.00312
DamerauLevenshtein	jellyfish	0.00591
DamerauLevenshtein	pyxdameraulevenshtein	0.03335
DamerauLevenshtein	textdistance	0.83524
Hamming	Levenshtein	0.00038
Hamming	rapidfuzz	0.00044
Hamming	jellyfish	0.00091
Hamming	textdistance	0.03531
Jaro	rapidfuzz	0.00092
Jaro	jellyfish	0.00191
Jaro	textdistance	0.07365
JaroWinkler	rapidfuzz	0.00094
JaroWinkler	jellyfish	0.00195
JaroWinkler	textdistance	0.07501
Levenshtein	rapidfuzz	0.00099
Levenshtein	Levenshtein	0.00122
Levenshtein	jellyfish	0.00254
Levenshtein	pylev	0.15688
Levenshtein	textdistance	0.53902

总计：24 个库。

确实很慢。请仅在安装了扩展的情况下将 TextDistance 用于生产环境。

Textdistance 会根据基准测试结果优化算法，并优先调用最快的外部库（如果可行）。

您也可以在本地手动运行基准测试：

pip install textdistance[benchmark]
python3 -m textdistance.benchmark

Textdistance 会显示针对您系统的基准测试结果表，并将库的优先级保存到 Textdistance 文件夹中的 libraries.json 文件中。此文件将用于选择最快的算法实现。默认的 libraries.json 已包含在软件包中。

运行测试

您只需要 task 工具即可。有关可用命令列表，请参阅 Taskfile.yml。例如，要运行包含第三方库的测试，可以执行 task pytest-external:run。

贡献

欢迎提交 PR！

• 发现了 bug？请修复它！
• 想添加更多算法？当然可以！只需确保新算法与库中现有算法采用相同的接口，并编写相应的测试用例。
• 能让某些功能更快吗？太好了！请尽量避免引入外部依赖，并记住所有功能不仅应适用于字符串。
• 还有其他您认为有益的想法吗？尽管去做吧！只要确保 CI 测试通过，并且 README 中的所有内容仍然适用（接口、特性等）。
• 没时间写代码？那就告诉您的朋友和关注者关于 textdistance 吧！用户越多，贡献越多，就越能带来更多令人惊叹的功能。

感谢您的支持 :heart:

TextDistance 快速上手指南

TextDistance 是一个功能强大的 Python 库，提供了 30 多种算法来计算两个或多个序列（字符串、列表等）之间的距离和相似度。它支持编辑距离、基于令牌、基于序列、压缩距离及语音算法等多种类型，且接口统一，使用简单。

环境准备

• 操作系统：Windows, macOS, Linux
• Python 版本：Python 3.6+
• 前置依赖：无强制外部依赖（纯 Python 实现），但为了获得最佳性能，建议安装额外的加速库。

安装步骤

1. 基础安装（纯 Python 实现）

适用于快速体验或对性能要求不高的场景：

pip install textdistance

国内用户推荐使用清华源加速：

pip install textdistance -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 高性能安装（推荐）

安装额外依赖库（如 rapidfuzz, jellyfish 等），可显著提升计算速度（生产环境必备）：

pip install "textdistance[extras]"

国内用户推荐使用清华源加速：

pip install "textdistance[extras]" -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 完整安装（含基准测试工具）

如果你需要进行性能基准测试或开发贡献：

pip install "textdistance[benchmark]"

基本使用

TextDistance 的所有算法都提供统一的接口，既可以直接调用快捷函数，也可以实例化类以自定义参数。

1. 最简用法（快捷函数）

直接导入库并调用算法名称作为函数，默认参数即可满足大多数需求。

import textdistance

# 计算汉明距离 (Hamming Distance)
dist = textdistance.hamming('test', 'text')
print(dist) 
# 输出: 1

# 计算相似度
sim = textdistance.hamming.similarity('test', 'text')
print(sim) 
# 输出: 3

# 计算归一化距离 (0.0 表示完全相同，1.0 表示完全不同)
norm_dist = textdistance.hamming.normalized_distance('test', 'text')
print(norm_dist) 
# 输出: 0.25

# 计算归一化相似度 (0.0 表示完全不同，1.0 表示完全相同)
norm_sim = textdistance.hamming.normalized_similarity('test', 'text')
print(norm_sim) 
# 输出: 0.75

2. 进阶用法（类实例化与参数定制）

通过实例化类，可以调整算法参数，例如设置 q-gram 大小或将输入按单词分割。

import textdistance

# 初始化汉明距离算法，设置 qval=2 (将字符串分为双字符组进行比较)
hamming_algo = textdistance.Hamming(qval=2)

result = hamming_algo.distance('test', 'text')
print(result) 
# 输出: 2 (因为 'te'=='te', 'es'!='ex', 'st'!='xt')

# 禁用外部加速库，强制使用纯 Python 实现
hamming_pure = textdistance.Hamming(external=False)
result_pure = hamming_pure('text', 'testit')
print(result_pure)

常用通用方法

所有算法类实例均支持以下方法：

• .distance(*sequences): 计算距离。
• .similarity(*sequences): 计算相似度。
• .normalized_distance(*sequences): 返回 0~1 之间的归一化距离。
• .normalized_similarity(*sequences): 返回 0~1 之间的归一化相似度。
• .maximum(*sequences): 返回该序列对可能的最大距离/相似度值。