TextDistance

Warnings

• breaking The `abydos` library support was dropped in version 4.6.0. If your code relied on the `textdistance` integration with `abydos`, it will break.
  Fix: Migrate to `rapidfuzz` or other external libraries for performance, or use `textdistance`'s pure Python implementations.
• breaking Python 2 support was dropped in version 4.2.0. The library now explicitly supports Python 3.6+.
  Fix: Upgrade your Python environment to Python 3.6 or newer.
• gotcha For optimal performance, especially in production environments, it is highly recommended to install `textdistance` with `[extras]` (e.g., `pip install textdistance[extras]`). Without these optional dependencies (like `rapidfuzz` and `numpy`), the pure Python implementations are significantly slower. [5, 7, 10]
  Fix: Install with `pip install textdistance[extras]` to leverage faster C-based implementations from external libraries. The library automatically prioritizes faster external libraries if found. [4, 14]
• gotcha The `Levenstein` algorithm was fixed in version 4.6.2 to ensure its return type is consistently `int`. If your application implicitly handled non-integer return values for Levenshtein distance prior to this version, its behavior might subtly change.
  Fix: Verify that your code correctly handles integer return types for Levenshtein distance calculations.
• gotcha By default, `textdistance` may try to use external libraries (like `rapidfuzz`) if they are installed and provide faster implementations for a given algorithm. This behavior is controlled by an internal `libraries.json` file. If you need to explicitly control which implementation is used or troubleshoot performance, be aware of this mechanism and the `external` argument. [4, 14]
  Fix: If you experience unexpected performance or behavior, inspect the `libraries.json` file in the `textdistance` package directory or use the `external=False` argument when instantiating an algorithm class to force pure Python implementation.

Install

• pip install textdistance Basic installation
• pip install textdistance[extras] Installation with optional faster dependencies (recommended for production)

Imports

• levenshtein

  import textdistance
  distance = textdistance.levenshtein.distance('text', 'test')

  Most algorithms are exposed as attributes of the `textdistance` module, providing both `distance` and `similarity` methods directly. [2, 3]
• JaroWinkler

  from textdistance import JaroWinkler
  jw = JaroWinkler()
  distance = jw.distance('martha', 'marhta')

  Algorithms can also be imported as classes for custom initialization parameters, though direct attribute access is common for default settings. [3, 14]

Quickstart

This quickstart demonstrates how to use the `textdistance` library to calculate various similarity and distance metrics. It shows direct method calls on algorithm objects (e.g., `textdistance.levenshtein.distance`) and also a convenience function for Jaro-Winkler. [2, 3, 6, 7]

import textdistance

# Calculate Levenshtein distance
str1 = "kitten"
str2 = "sitting"
distance = textdistance.levenshtein.distance(str1, str2)
similarity = textdistance.levenshtein.similarity(str1, str2)
normalized_distance = textdistance.levenshtein.normalized_distance(str1, str2)
normalized_similarity = textdistance.levenshtein.normalized_similarity(str1, str2)

print(f"Strings: '{str1}', '{str2}'")
print(f"Levenshtein Distance: {distance}")
print(f"Levenshtein Similarity: {similarity}")
print(f"Levenshtein Normalized Distance: {normalized_distance:.2f}")
print(f"Levenshtein Normalized Similarity: {normalized_similarity:.2f}")

# Example with another algorithm (Jaro-Winkler)
str3 = "martha"
str4 = "marhta"
jaro_winkler_similarity = textdistance.jaro_winkler(str3, str4)
print(f"\nJaro-Winkler Similarity between '{str3}' and '{str4}': {jaro_winkler_similarity:.2f}")