Metadata-Version: 2.4
Name: strprob
Version: 1.0.4
Summary: A string comparison tool
Home-page: https://github.com/spmather/strprob
Author-email: spmather <spm-pypi-issues@pm.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/spmather/strprob
Project-URL: Issues, https://github.com/spmather/strprob/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# strprob

Brief note:  prior versions are named "pstr," however, this is a reserved name in PyPI and was renamed for compatibility.  There is no version difference up to v1.0.4.

strprob is a small fuzzy string comparison tool in python for comparing two strings and how closely they match using the equation:  `( (common words/total words) + (common characters/total characters) ) / (the mean of the input)`.  The output is an number between 0 and 1, including float values.

# When to use

There are a few times when a regex is not powerful enough without significant modification to compare strings for matching.  I created this fuzzy string to accomodate specific needs I had.

# Math

The equation that is calculated is a probability range from 0 to 1 based on how closely the strings match characters and words.

##### Working through the math

A single word comparison:  `Car` and `Cat` 

```
# Comparing Characters
C = C ... 100%
A = A ... 100%
R != T ... 0%
# Matches/Total = 4/6
# Result:  0.66 match


# Comparing words
Cat != Car ... 0%
# Matches/Total = 0/2
# Result: 0.00 match


# Mean of characters and words
0.66 + 0.00 / 2 = 0.33 or 33% match
```

A multiple word comparison:  `Hello my new friend` and `Hello my old friend`

```
# Comparing Characters
H = H ... 100%
E = E ... 100%
L = L ... 100%
L = L ... 100%
O = O ... 100%
M = M ... 100%
Y = Y ... 100%
N != O ... 0%
E != L ... 0%
W != D ... 0%
F = F ... 100%
R = R ... 100%
I = I ... 100%
E = E ... 100%
N = N ... 100%
D = D ... 100%
# Matches/Total = 26/32
# Result:  0.8125 match


# Comparing words
Hello = Hello ... 100%
My = My ... 100%
New != Old ... 0%
Friend = Friend ... 100%
# Matches/Total = 6/8
# Result: 0.75 match


# Mean of characters and words
(0.8125 + 0.75) / 2 = 0.78125 or 78.125% match
```



##### Accuracy

I have used this over several workloads and typically, I will put the accuracy threshhold at `0.859` for important work.  I.E.

```powershell
$strprobValue = ./strprob.py strprobd "string 1 here" "string 2 here"

if ($strprobValue -gt 0.859) {
    # do your command
}
```

I also find it to have excellent use at the end of any `if` chains/statements involving matching a string to regex or any string-related validation:

```powershell
$strprobValue = ./strprob.py strprobd "string 1 here" "string 2 here"

if ($something -match $regex) {
    # do your command
}
elseif ($strprobValue -gt 0.859) {
    # do your command
}
```

##### In summary

1. Above `0.949` = Too high for most uses

2. `0.859` = Highly accurate

3. `0.799` = Pretty good accurate

4. `0.649` = Absolute minimum for most uses

5. Below `0.549` = Patently inaccurate

##### Windows

```powershell
pip install strprob
```



##### Linux

If the package is not added to your distro's repo, then you need to create a venv like this:

```bash
# Makes a directory at a path.  Change 
#     "/path/to/new/virtual/environment"
#     to an actual path in your file system
mkdir /path/to/new/virtual/environment

# Create the virtual environment
# Some distros do not come packaged with venv
#    follow the install prompts to add python3-venv
#    if applicable
python -m venv /path/to/new/virtual/environment

# Use the new venv
source /path/to/new/virtual/environment/bin/activate

# Install the strprob package
pip install strprob
```



##### Next use the following syntax

From PowerShell or Bash

1. Example 1:  Comparing the similarity of `"string 1 here"` and `"string 2 here"`

```
./strprob.py strprob "string 1 here" "string 2 here"
```

2. Example 2:  Comparing the similarity of `"string 1 here"` and `"string 2 here"` but with debug

   

```
./strprob.py strprobd "string 1 here" "string 2 here"
```

### Future plans
1. add case insensitive options
2. fix the brute force recursion in some cases where 1,000 iterations doesn't remove items from the character lists
