stringmatch 0.5.0

A library to match and compare strings.

Stringmatch

Yet another small, lightweight string matching library written in Python, based on the Levenshtein distance and the Levenshtein Python C Extension.
Inspired by seatgeek/thefuzz, which did not quite fit my needs, so I am building this library for myself, primarily.

Table of Contents

• Requirements
• Installation
• Basic Usage
  • Matching
  • Ratios
  • Matching & Ratios
  • Strings
• Advanced Usage
  • Keyword Arguments
  • Scoring Algorithms
• Links

Requirements

• Python 3.9 or later.

Installation

Install the latest stable version with pip:

pip install stringmatch

Or install the newest version via git (Might be unstable/unfinished):

pip install -U git+https://github.com/atomflunder/stringmatch

Basic Usage

Matching

The match functions allow you to compare 2 strings and check if they are "similar enough" to each other, or get the best match(es) from a list of strings:

from stringmatch import Match

match = Match()

# Checks if the strings are similar.
match.match("searchlib", "srchlib")           # returns True
match.match("searchlib", "something else")    # returns False

# Returns the best match(es) found in the list.
searches = ["searchli", "searhli", "search", "lib", "whatever", "s"]
match.get_best_match("searchlib", searches)   # returns "searchli"
match.get_best_matches("searchlib", searches) # returns ['searchli', 'searhli', 'search']

Ratios

You can get the "ratio of similarity" between strings like this:

from stringmatch import Ratio

ratio = Ratio()

# Getting the ratio between the two strings.
ratio.ratio("searchlib", "searchlib")   # returns 100
ratio.ratio("searchlib", "srechlib")    # returns 82

# Getting the ratio between the first string and the list of strings at once.
searches = ["searchlib", "srechlib"]
ratio.ratio_list("searchlib", searches) # returns [100, 82]

Matching & Ratios

You can also get both the match and the ratio together in a tuple using these functions:

from stringmatch import Match

match = Match()
searches = ["test", "nope", "tset"]

match.match_with_ratio("searchlib", "srechlib")       # returns (True, 82)
match.get_best_match_with_ratio("test", searches)     # returns ("test", 100)
match.get_best_matches_with_ratio("test", searches)   # returns [("test", 100), ("tset", 75)]

Strings

This is primarily meant for internal usage, but you can also use this library to modify strings:

from stringmatch import Strings

strings = Strings()

strings.latinise("Héllö, world!")               # returns "Hello, world!"
strings.remove_punctuation("wh'at;, ever")      # returns "what ever"
strings.only_letters("Héllö, world!")           # returns "Hll world"
strings.ignore_case("test test!", lower=False)  # returns "TEST TEST!"

Advanced Usage

Keyword Arguments

You can pass in additional arguments for the Match() functions to customise your search further:

score=70
The score cutoff for matching, by default set to 70.

match("searchlib", "srechlib", score=85)    # returns False
match("searchlib", "srechlib", score=70)    # returns True

---

limit=5
The limit of how many matches to return. Only available for Matches().get_best_matches(). If you want to return every match set this to 0. By default this is set to 5.

searches = ["limit 5", "limit 4", "limit 3", "limit 2", "limit 1", "limit 0"]
get_best_matches("limit 5", searches, limit=2)  # returns ["limit 5", "limit 4"]
get_best_matches("limit 5", searches, limit=1)  # returns ["limit 5"]

---

latinise=False
Replaces special unicode characters with their latin alphabet equivalents. By default turned off.

match("séärçh", "search", latinise=True)    # returns True
match("séärçh", "search", latinise=False)   # returns False

---

ignore_case=False
If you want to ignore case sensitivity while searching. By default turned off.

match("test", "TEST", ignore_case=True)     # returns True
match("test", "TEST", ignore_case=False)    # returns False

---

remove_punctuation=False
Removes commonly used punctuation symbols from the strings, like .,;:!? and so on. By default turned off.

match("test,---....", "test", remove_punctuation=True)  # returns True
match("test,---....", "test", remove_punctuation=False) # returns False

---

only_letters=False
Removes every character that is not in the latin alphabet, a more extreme version of remove_punctuation. By default turned off.

match("»»ᅳtestᅳ►", "test", only_letters=True)   # returns True
match("»»ᅳtestᅳ►", "test", only_letters=False)  # returns False

Scoring Algorithms

You can pass in different scoring algorithms when initialising the Match() and Ratio() classes.
The available options are: "levenshtein", "jaro", "jaro_winkler".
Different algorithms will produce different results, obviously. By default set to "levenshtein".

levenshtein_matcher = Match(scorer="levenshtein")
jaro_winkler_matcher = Match(scorer="jaro_winkler")

levenshtein_matcher.match("test", "th test")  # returns True (score = 73)
jaro_winkler_matcher.match("test", "th test") # returns False (score = 60)

Links

Packages used:

• Levenshtein
• Unidecode

Related packages:

• thefuzz