Python開發者實戰：從 0.4 分到 1.0 分 —— 打造一個「懂人心」的檔案模糊搜尋系統; difflib.SequenceMatcher

# %%
import difflib

query = "nic"
target = "nic mac test"
# 計算相似度分數
# 公式: 2 * 匹配長度 / (A長度 + B長度)
#       2 * 3      / (3 + 12) = 6/15 = 0.4
score = difflib.SequenceMatcher(None, query, target).ratio()

print(f"'{query}' vs '{target}' 分數: {score}")
# 輸出: 'nic' vs 'nic mac test' 分數: 0.4

# %%
import difflib

query = "nic"
target = "nic mac test"
# 計算相似度分數
# 公式: 2 * 匹配長度 / (A長度 + B長度)
#       2 * 3      / (3 + 12) = 6/15 = 0.4
score = difflib.SequenceMatcher(None, query, target).ratio()

print(f"'{query}' vs '{target}' 分數: {score}")
# 輸出: 'nic' vs 'nic mac test' 分數: 0.4

import difflib
from pathlib import Path

def smart_search(user_query, file_paths):
    results = []
    
    # 預處理：將檔名切割並建立索引
    # 使用 p.stem 去除副檔名 (.docx)，讓比對更乾淨
    file_db = {p.name: p.stem.split("__") for p in file_paths}

    print(f"查詢: '{user_query}'\n" + "-"*30)

    for filename, segments in file_db.items():
        # 轉小寫以忽略大小寫差異
        segments_lower = [seg.lower() for seg in segments]
        query_lower = user_query.lower()

        # --- 策略 A: 完全命中 (給滿分) ---
        # 解決 'nic' vs 'nic mac test' 分數只有 0.4 的問題
        if any(query_lower in seg for seg in segments_lower):
            results.append((1.0, filename, f"【精確命中】包含 '{user_query}'"))
            continue  # 找到滿分就不用往下算了
        
        # --- 策略 B: 模糊比對 (容忍錯字) ---
        # 解決 'NIC MACK' vs 'NIC MAC' 的問題
        # cutoff=0.6: 過濾掉像 "common tools" 這種相似度 0.42 的雜訊
        matches = difflib.get_close_matches(query_lower, segments_lower, 
                  n=1, cutoff=0.6)
        
        if matches:
            best_match = matches[0]
            # 這裡才真正使用 difflib 的分數
            score = difflib.SequenceMatcher(None, query_lower, best_match).ratio()
            results.append((score, filename, f"【模糊建議】修正為 '{best_match}'"))

    return results

# --- 測試數據 ---
files = [
    Path("C:/Tests/UserA__ProjectX__nic mac test.docx"),       # 目標 1 (含有分隔線)
    Path("C:/Tests/UserA__ProjectY__switch uart test.docx"),   # 干擾項
    Path("C:/Tests/Common__Lib__diagnostic tool.docx")         # 雜訊 (0.42)
]

# 測試 1: 使用者想找 nic (短關鍵字)
# 結果: 獲得 1.0 分 (原本只有 0.4)
results = smart_search("NIC", files)
results.sort(key=lambda x: x[0], reverse=True)
for score, name, reason in results:
    print(f"[{score:.2f}] {name} -> {reason}")

print("\n" + "="*30 + "\n")

# 測試 2: 使用者不小心打錯字 (MACK)
# 結果: 獲得約 0.8 分 (成功救回)
results = smart_search("NIC MACK TEST", files)
results.sort(key=lambda x: x[0], reverse=True)
for score, name, reason in results:
    print(f"[{score:.2f}] {name} -> {reason}")

import difflib
from pathlib import Path

def smart_search(user_query, file_paths):
    results = []
    
    # 預處理：將檔名切割並建立索引
    # 使用 p.stem 去除副檔名 (.docx)，讓比對更乾淨
    file_db = {p.name: p.stem.split("__") for p in file_paths}

    print(f"查詢: '{user_query}'\n" + "-"*30)

    for filename, segments in file_db.items():
        # 轉小寫以忽略大小寫差異
        segments_lower = [seg.lower() for seg in segments]
        query_lower = user_query.lower()

        # --- 策略 A: 完全命中 (給滿分) ---
        # 解決 'nic' vs 'nic mac test' 分數只有 0.4 的問題
        if any(query_lower in seg for seg in segments_lower):
            results.append((1.0, filename, f"【精確命中】包含 '{user_query}'"))
            continue  # 找到滿分就不用往下算了
        
        # --- 策略 B: 模糊比對 (容忍錯字) ---
        # 解決 'NIC MACK' vs 'NIC MAC' 的問題
        # cutoff=0.6: 過濾掉像 "common tools" 這種相似度 0.42 的雜訊
        matches = difflib.get_close_matches(query_lower, segments_lower, 
                  n=1, cutoff=0.6)
        
        if matches:
            best_match = matches[0]
            # 這裡才真正使用 difflib 的分數
            score = difflib.SequenceMatcher(None, query_lower, best_match).ratio()
            results.append((score, filename, f"【模糊建議】修正為 '{best_match}'"))

    return results

# --- 測試數據 ---
files = [
    Path("C:/Tests/UserA__ProjectX__nic mac test.docx"),       # 目標 1 (含有分隔線)
    Path("C:/Tests/UserA__ProjectY__switch uart test.docx"),   # 干擾項
    Path("C:/Tests/Common__Lib__diagnostic tool.docx")         # 雜訊 (0.42)
]

# 測試 1: 使用者想找 nic (短關鍵字)
# 結果: 獲得 1.0 分 (原本只有 0.4)
results = smart_search("NIC", files)
results.sort(key=lambda x: x[0], reverse=True)
for score, name, reason in results:
    print(f"[{score:.2f}] {name} -> {reason}")

print("\n" + "="*30 + "\n")

# 測試 2: 使用者不小心打錯字 (MACK)
# 結果: 獲得約 0.8 分 (成功救回)
results = smart_search("NIC MACK TEST", files)
results.sort(key=lambda x: x[0], reverse=True)
for score, name, reason in results:
    print(f"[{score:.2f}] {name} -> {reason}")

difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)

difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)

Init signature: difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)
Docstring:     
SequenceMatcher is a flexible class for comparing pairs of sequences of
any type, so long as the sequence elements are hashable.  The basic
algorithm predates, and is a little fancier than, an algorithm
published in the late 1980's by Ratcliff and Obershelp under the
hyperbolic name "gestalt pattern matching".  The basic idea is to find
the longest contiguous matching subsequence that contains no "junk"
elements (R-O doesn't address junk).  The same idea is then applied
recursively to the pieces of the sequences to the left and to the right
of the matching subsequence.  This does not yield minimal edit
sequences, but does tend to yield matches that "look right" to people.

SequenceMatcher tries to compute a "human-friendly diff" between two
sequences.  Unlike e.g. UNIX(tm) diff, the fundamental notion is the
longest *contiguous* & junk-free matching subsequence.  That's what
catches peoples' eyes.  The Windows(tm) windiff has another interesting
notion, pairing up elements that appear uniquely in each sequence.
That, and the method here, appear to yield more intuitive difference
reports than does diff.  This method appears to be the least vulnerable
to syncing up on blocks of "junk lines", though (like blank lines in
ordinary text files, or maybe "<P>" lines in HTML files).  That may be
because this is the only method of the 3 that has a *concept* of
"junk" <wink>.

Example, comparing two strings, and considering blanks to be "junk":

>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")
>>>

.ratio() returns a float in [0, 1], measuring the "similarity" of the
sequences.  As a rule of thumb, a .ratio() value over 0.6 means the
sequences are close matches:

>>> print(round(s.ratio(), 3))
0.866
>>>

If you're only interested in where the sequences match,
.get_matching_blocks() is handy:

>>> for block in s.get_matching_blocks():
...     print("a[%d] and b[%d] match for %d elements" % block)
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 21 elements
a[29] and b[38] match for 0 elements

Note that the last tuple returned by .get_matching_blocks() is always a
dummy, (len(a), len(b), 0), and this is the only case in which the last
tuple element (number of elements matched) is 0.

If you want to know how to change the first sequence into the second,
use .get_opcodes():

>>> for opcode in s.get_opcodes():
...     print("%6s a[%d:%d] b[%d:%d]" % opcode)
 equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
 equal a[8:29] b[17:38]

See the Differ class for a fancy human-friendly file differencer, which
uses SequenceMatcher both to compare sequences of lines, and to compare
sequences of characters within similar (near-matching) lines.

See also function get_close_matches() in this module, which shows how
simple code building on SequenceMatcher can be used to do useful work.

Timing:  Basic R-O is cubic time worst case and quadratic time expected
case.  SequenceMatcher is quadratic time for the worst case and has
expected-case behavior dependent in a complicated way on how many
elements the sequences have in common; best case time is linear.
Init docstring:
Construct a SequenceMatcher.

Optional arg isjunk is None (the default), or a one-argument
function that takes a sequence element and returns true iff the
element is junk.  None is equivalent to passing "lambda x: 0", i.e.
no elements are considered to be junk.  For example, pass
    lambda x: x in " \t"
if you're comparing lines as sequences of characters, and don't
want to synch up on blanks or hard tabs.

Optional arg a is the first of two sequences to be compared.  By
default, an empty string.  The elements of a must be hashable.  See
also .set_seqs() and .set_seq1().

Optional arg b is the second of two sequences to be compared.  By
default, an empty string.  The elements of b must be hashable. See
also .set_seqs() and .set_seq2().

Optional arg autojunk should be set to False to disable the
"automatic junk heuristic" that treats popular elements as junk
(see module documentation for more information).
File:           c:\users\appdata\local\programs\python\python311\lib\difflib.py
Type:           type
Subclasses:

Init signature: difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)
Docstring:     
SequenceMatcher is a flexible class for comparing pairs of sequences of
any type, so long as the sequence elements are hashable.  The basic
algorithm predates, and is a little fancier than, an algorithm
published in the late 1980's by Ratcliff and Obershelp under the
hyperbolic name "gestalt pattern matching".  The basic idea is to find
the longest contiguous matching subsequence that contains no "junk"
elements (R-O doesn't address junk).  The same idea is then applied
recursively to the pieces of the sequences to the left and to the right
of the matching subsequence.  This does not yield minimal edit
sequences, but does tend to yield matches that "look right" to people.

SequenceMatcher tries to compute a "human-friendly diff" between two
sequences.  Unlike e.g. UNIX(tm) diff, the fundamental notion is the
longest *contiguous* & junk-free matching subsequence.  That's what
catches peoples' eyes.  The Windows(tm) windiff has another interesting
notion, pairing up elements that appear uniquely in each sequence.
That, and the method here, appear to yield more intuitive difference
reports than does diff.  This method appears to be the least vulnerable
to syncing up on blocks of "junk lines", though (like blank lines in
ordinary text files, or maybe "<P>" lines in HTML files).  That may be
because this is the only method of the 3 that has a *concept* of
"junk" <wink>.

Example, comparing two strings, and considering blanks to be "junk":

>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")
>>>

.ratio() returns a float in [0, 1], measuring the "similarity" of the
sequences.  As a rule of thumb, a .ratio() value over 0.6 means the
sequences are close matches:

>>> print(round(s.ratio(), 3))
0.866
>>>

If you're only interested in where the sequences match,
.get_matching_blocks() is handy:

>>> for block in s.get_matching_blocks():
...     print("a[%d] and b[%d] match for %d elements" % block)
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 21 elements
a[29] and b[38] match for 0 elements

Note that the last tuple returned by .get_matching_blocks() is always a
dummy, (len(a), len(b), 0), and this is the only case in which the last
tuple element (number of elements matched) is 0.

If you want to know how to change the first sequence into the second,
use .get_opcodes():

>>> for opcode in s.get_opcodes():
...     print("%6s a[%d:%d] b[%d:%d]" % opcode)
 equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
 equal a[8:29] b[17:38]

See the Differ class for a fancy human-friendly file differencer, which
uses SequenceMatcher both to compare sequences of lines, and to compare
sequences of characters within similar (near-matching) lines.

See also function get_close_matches() in this module, which shows how
simple code building on SequenceMatcher can be used to do useful work.

Timing:  Basic R-O is cubic time worst case and quadratic time expected
case.  SequenceMatcher is quadratic time for the worst case and has
expected-case behavior dependent in a complicated way on how many
elements the sequences have in common; best case time is linear.
Init docstring:
Construct a SequenceMatcher.

Optional arg isjunk is None (the default), or a one-argument
function that takes a sequence element and returns true iff the
element is junk.  None is equivalent to passing "lambda x: 0", i.e.
no elements are considered to be junk.  For example, pass
    lambda x: x in " \t"
if you're comparing lines as sequences of characters, and don't
want to synch up on blanks or hard tabs.

Optional arg a is the first of two sequences to be compared.  By
default, an empty string.  The elements of a must be hashable.  See
also .set_seqs() and .set_seq1().

Optional arg b is the second of two sequences to be compared.  By
default, an empty string.  The elements of b must be hashable. See
also .set_seqs() and .set_seq2().

Optional arg autojunk should be set to False to disable the
"automatic junk heuristic" that treats popular elements as junk
(see module documentation for more information).
File:           c:\users\appdata\local\programs\python\python311\lib\difflib.py
Type:           type
Subclasses: