A library to match and compare strings.
Project description
stringmatch
stringmatch is a small, lightweight string matching library written in Python, based on the Levenshtein distance and the Levenshtein Python C Extension.
Inspired by libraries like seatgeek/thefuzz, which did not quite fit my needs. And so I am building this library for myself, primarily.
Disclaimer: This library is still in an alpha development phase! Changes may be frequent and breaking changes can occur! It is recommended to update frequently to minimise bugs and maximise features.
Table of Contents
- 🎯 Key Features
- 📋 Requirements
- ⚙️ Installation
- 🔨 Basic Usage
- 🛠️ Advanced Usage
- 🌟 Contributing
- 🔗 Links
- ⚠️ License
Key Features
This library matches compares and strings to each other based mainly on, among others, the Levenshtein distance.
What makes stringmatch special compared to other libraries with similar functions:
- 💨 Lightweight, straightforward and easy to use
- ⚡ Very high speed, 2-10x faster while providing better search results
- 🧰 Allows for highly customisable searches
- 📚 Lots of utility functions to make your life easier
- 🌍 Handles special unicode characters, like emojis or characters from other languages, like ジャパニーズ
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 or 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("stringmatch", "strngmach") # returns True
match.match("stringmatch", "something else") # returns False
# Returns the best match(es) found in the list:
searches = ["stringmat", "strinma", "strings", "mtch", "whatever", "s"]
match.get_best_match("stringmatch", searches) # returns "stringmat"
match.get_best_matches("stringmatch", searches) # returns ["stringmat", "strinma"]
Ratios
The "ratio of similarity" describes how similar the strings are to each other. It ranges from 100 being an exact match to 0 being something completely different.
You can get the ratio between strings like this:
from stringmatch import Ratio
ratio = Ratio()
# Getting the ratio between the two strings:
ratio.ratio("stringmatch", "stringmatch") # returns 100
ratio.ratio("stringmatch", "strngmach") # returns 90
ratio.ratio("stringmatch", "eh") # returns 15
# Getting the ratio between the first string and the list of strings at once:
searches = ["stringmatch", "strngmach", "eh"]
ratio.ratio_list("stringmatch", searches) # returns [100, 90, 15]
# Searching for partial ratios with substrings:
ratio.partial_ratio("a string", "a string longer") # returns 80
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()
match.match_with_ratio("stringmatch", "strngmach") # returns (True, 90)
searches = ["test", "nope", "tset"]
match.get_best_match_with_ratio("test", searches) # returns ("test", 100)
match.get_best_matches_with_ratio("test", searches) # returns [("test", 100), ("tset", 75)]
Distances
Instead of the ratio, you can also get the Levenshtein distance between strings directly. The bigger the distance, the more different the strings:
from stringmatch import Distance
distance = Distance()
distance.distance("kitten", "sitting") # returns 3
searches = ["sitting", "kitten"]
distance.distance_list("kitten", searches) # returns [3, 0]
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
There are some optional arguments available for a few functions.
score
Type | Default | Description |
---|---|---|
Integer | 70 | The score cutoff for matching. Only available for Match() functions. |
# Example:
match("stringmatch", "strngmach", score=95) # returns False
match("stringmatch", "strngmach", score=70) # returns True
limit
Type | Default | Description |
---|---|---|
Integer | 5 | The limit of how many matches to return. If you want to return every match set this to 0 or None. Only available for the functions that return multiple matches. |
# Example:
searches = ["limit 5", "limit 4", "limit 3", "limit 2", "limit 1", "limit 0", "something else"]
# returns ["limit 5", "limit 4"]
get_best_matches("limit 5", searches, limit=2)
# returns ["limit 5"]
get_best_matches("limit 5", searches, limit=1)
# returns ["limit 5", "limit 4", "limit 3", "limit 2", "limit 1", "limit 0"]
get_best_matches("limit 5", searches, limit=None)
Class Keyword Arguments
You can also pass in on or more of these optional arguments when initialising the Match()
and Ratio()
classes to customize your search even further.
Of course you can use multiple of these keyword arguments at once, to customise the search to do exactly what you intend to do.
scorer
Type | Default | Description |
---|---|---|
_Scorer | LevenshteinScorer | Different scoring algorithms to use. The available options are: LevenshteinScorer , JaroScorer , JaroWinklerScorer . |
Click on the links above for detailed information about these, but speaking generally the Jaro Scorer will be the fastest, focussing on the characters the strings have in common.
The Jaro-Winkler Scorer slightly modified the Jaro Scorer to prioritise characters at the start of the string.
The Levenshtein Scorer will, most likely, produce the best results, focussing on the number of edits needed to get from one string to the other.
# Example:
from stringmatch import Match, LevenshteinScorer, JaroWinklerScorer
lev_matcher = Match(scorer=LevenshteinScorer)
lev_matcher.match_with_ratio("test", "th test") # returns (True, 73)
jw_matcher = Match(scorer=JaroWinklerScorer)
jw_matcher.match_with_ratio("test", "th test") # returns (False, 60)
latinise
Type | Default | Description |
---|---|---|
Boolean | False | Replaces special unicode characters with their latin alphabet equivalents. Examples: Ǽ -> AE , ノース -> nosu |
# Example:
lat_match = Match(latinise=True)
lat_match.match("séärçh", "search") # returns True
def_match = Match(latinise=False)
def_match.match("séärçh", "search") # returns False
ignore_case
Type | Default | Description |
---|---|---|
Boolean | False | If you want to ignore case sensitivity while searching. |
# Example:
case_match = Match(ignore_case=True)
case_match.match("test", "TEST") # returns True
def_match = Match(ignore_case=False)
def_match.match("test", "TEST") # returns False
remove_punctuation
Type | Default | Description |
---|---|---|
Boolean | False | Removes commonly used punctuation symbols from the strings, like .,;:!? and so on. |
# Example:
punc_match(remove_punctuation=True)
punc_match.match("test,---....", "test") # returns True
def_match = Match(remove_punctuation=False)
def_match.match("test,---....", "test") # returns False
only_letters
Type | Default | Description |
---|---|---|
Boolean | False | Removes every character that is not a number or in the latin alphabet, a more extreme version of remove_punctuation . |
# Example:
let_match = Match(only_letters=True)
let_match.match("»»ᅳtestᅳ►", "test") # returns True
def_match = Match(only_letters=False)
def_match.match("»»ᅳtestᅳ►", "test") # returns False
include_partial
Type | Default | Description |
---|---|---|
Boolean | False | If set to true, also searches for partial substring matches. This may lead to more desirable results but is a bit slower. If the strings are very far apart in length this will return 60% of its value, if they are moderately far apart, 80%. |
# Example:
part_match = Match(include_partial=True)
# returns (True, 60)
part_match.match_with_ratio("A string", "A string thats like really really long", score=60)
def_match = Match(include_partial=False)
# returns (False, 35)
def_match.match_with_ratio("A string", "A string thats like really really long", score=60)
Contributing
Contributions to this library are always appreciated! If you have any sort of feedback, or are interested in contributing, head on over to the Contributing Guidelines.
Additionally, if you like this library, leaving a star and spreading the word would be appreciated a lot!
Thanks in advance for taking the time to do so.
Links
Packages used:
Related packages:
License
This project is licensed under the MIT License.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for stringmatch-0.10.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cfe5245cf397a1a2840dd06282a19b8b5870b72da4a7f61d92fc823b18dde6f3 |
|
MD5 | 58e7835f94058dd32e84ffc75cb0e3d5 |
|
BLAKE2b-256 | 472668d3098df041ef39a214f725f62aacf8a41db97e5e25c71840310b22ef61 |