tai/research/fuzzy-matching-selectors/python-docs-difflib.md

difflib - Helpers for computing deltas (Python docs)

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	fuzzy-matching-selectors
Document type	Source Dossier
Tier	1
Source title	difflib - Helpers for computing deltas (Python docs)
Source URL	https://docs.python.org/3/library/difflib.html
Source publisher / author	Python Software Foundation
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

Official documentation of SequenceMatcher (Ratcliff/Obershelp variant) and get_close_matches.

Key findings

• ratio() = 2.0*M/T; over 0.6 is a rule of thumb for close matches; quick_ratio and real_quick_ratio are upper bounds.
• autojunk: for a second sequence of 200+ items, items above 1% frequency are junk; asymmetric.
• get_close_matches(word, possibilities, n=3, cutoff=0.6) returns the best matches sorted by score, most similar first.
• The algorithm finds the longest contiguous common block then recurses left and right; the docs say the base algorithm is cubic worst case, quadratic expected, and difflib's is quadratic worst case.
• Examples: get_close_matches('appel', ['ape','apple','peach','puppy']) = ['apple','ape'].

Pros / strengths

Canonical stdlib reference with a published cutoff default (0.6).

Cons / limitations / caveats

Gestalt matching has no boundary or camelCase awareness and is asymmetric in its junk heuristic. The result is a heuristic, not a minimal edit.

Relevance to tai

tai already contains sequencematcher.cpp; it was evaluated and not used for ids because it lacks boundary bonuses. The 0.6 cutoff default informed choosing a documented floor (tai: 0.3, lower on purpose, see the conclusion).

Changelog

Date	Change
2026-10-25	Initial dossier created.