Benchmark alternatives

.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Publish to PyPI
 on:
   push:
     tags:
-      - 'v*'
+      - 'v*.*.*'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

README.md

@@ -1,7 +1,7 @@
 # sane-contractions
 
 [![Tests](https://github.com/devjerry0/sane-contractions/actions/workflows/commit.yml/badge.svg)](https://github.com/devjerry0/sane-contractions/actions/workflows/commit.yml)
-[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/devjerry0/sane-contractions)
+[![codecov](https://codecov.io/gh/devjerry0/sane-contractions/branch/main/graph/badge.svg)](https://codecov.io/gh/devjerry0/sane-contractions)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -31,18 +31,22 @@ pip install sane-contractions
 uv pip install sane-contractions
 ```
 
-[uv](https://github.com/astral-sh/uv) is 10-100x faster than pip and is a drop-in replacement.
+[uv](https://github.com/astral-sh/uv)
 
 ## Quick Start
 
 ```python
 import contractions
 
-contractions.fix("you're happy now")
+contractions.expand("you're happy now")
 # "you are happy now"
 
-contractions.fix("I'm sure you'll love it!")
+contractions.expand("I'm sure you'll love it!")
 # "I am sure you will love it!"
+
+# Shorthand aliases
+contractions.e("you're")  # "you are"
+contractions.p("you're", 5)  # preview with context
 ```
 
 ## Usage
@@ -53,21 +57,21 @@ contractions.fix("I'm sure you'll love it!")
 import contractions
 
 text = "I'm sure you're going to love what we've done"
-expanded = contractions.fix(text)
+expanded = contractions.expand(text)
 print(expanded)
 # "I am sure you are going to love what we have done"
 ```
 
 ### Controlling Slang Expansion
 
 ```python
-contractions.fix("yall're gonna love this", slang=True)
+contractions.expand("yall're gonna love this", slang=True)
 # "you all are going to love this"
 
-contractions.fix("yall're gonna love this", slang=False)
+contractions.expand("yall're gonna love this", slang=False)
 # "yall are going to love this"
 
-contractions.fix("yall're gonna love this", leftovers=False)
+contractions.expand("yall're gonna love this", leftovers=False)
 # "yall are gonna love this"
 ```
 
@@ -76,9 +80,9 @@ contractions.fix("yall're gonna love this", leftovers=False)
 The library intelligently preserves the case pattern of the original contraction:
 
 ```python
-contractions.fix("you're happy")    # "you are happy"
-contractions.fix("You're happy")    # "You are happy"
-contractions.fix("YOU'RE HAPPY")    # "YOU ARE HAPPY"
+contractions.expand("you're happy")    # "you are happy"
+contractions.expand("You're happy")    # "You are happy"
+contractions.expand("YOU'RE HAPPY")    # "YOU ARE HAPPY"
 ```
 
 ### Adding Custom Contractions
@@ -87,7 +91,7 @@ Add a single contraction:
 
 ```python
 contractions.add('myword', 'my word')
-contractions.fix('myword is great')
+contractions.expand('myword is great')
 # "my word is great"
 ```
 
@@ -102,17 +106,17 @@ custom_contractions = {
 }
 contractions.add_dict(custom_contractions)
 
-contractions.fix("ain't gonna happen")
+contractions.expand("ain't gonna happen")
 # "are not going to happen"
 ```
 
 Load contractions from a JSON file:
 
 ```python
 # custom_contractions.json contains: {"myterm": "my expansion", "another": "another word"}
-contractions.load_json("custom_contractions.json")
+contractions.load_file("custom_contractions.json")
 
-contractions.fix("myterm is great")
+contractions.expand("myterm is great")
 # "my expansion is great"
 ```
 
@@ -137,7 +141,7 @@ for item in preview:
 
 ## API Reference
 
-### `fix(text, leftovers=True, slang=True)`
+### `expand(text, leftovers=True, slang=True)`
 
 Expands contractions in the given text.
 
@@ -163,7 +167,7 @@ Adds multiple custom contractions at once.
 **Parameters:**
 - `dictionary` (dict): Dictionary mapping contractions to their expansions
 
-### `load_json(filepath)`
+### `load_file(filepath)`
 
 Loads custom contractions from a JSON file.
 
@@ -180,7 +184,7 @@ Preview contractions in text before expanding.
 
 **Parameters:**
 - `text` (str): The text to analyze
-- `flank` (int): Number of characters to show before/after each match
+- `context_chars` (int): Number of characters to show before/after each match
 
 **Returns:** `list[dict]` - List of matches with context information
 
@@ -280,7 +284,7 @@ This fork includes several enhancements over the original `contractions` library
 
 ### 🆕 New Features
 - **`add_dict()`** - Bulk add custom contractions from a dictionary
-- **`load_json()`** - Load contractions from JSON files
+- **`load_file()`** - Load contractions from JSON files
 - **Type hints** - Full type coverage with mypy validation
 - **Better structure** - Modular code organization (core, api modules)
 

contractions/__init__.py

@@ -1,5 +1,16 @@
+import warnings
+
 from ._version import __version__
-from .api import add, add_dict, load_json, preview
-from .core import fix
+from .api import add, add_dict, e, expand, load_file, p, preview
+
+
+def fix(*args, **kwargs):
+    warnings.warn(
+        "fix() is deprecated and will be removed in v1.0.0. Use expand() instead.",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return expand(*args, **kwargs)
+
 
-__all__ = ["fix", "add", "add_dict", "load_json", "preview", "__version__"]
+__all__ = ["expand", "fix", "add", "add_dict", "load_file", "preview", "e", "p", "__version__"]

contractions/api.py

@@ -1,47 +1,28 @@
-import json
+from .extensions import add_custom_contraction, add_custom_dict, load_custom_from_file
+from .processor import expand as _expand
+from .processor import preview as _preview
 
-from .core import replacers, ts_view_window
 
+def expand(text: str, leftovers: bool = True, slang: bool = True) -> str:
+    return _expand(text, leftovers, slang)
 
-def add(key, value):
-    for ts in replacers.values():
-        ts.add(key, value)
-    ts_view_window.add([key])
 
+def preview(text: str, context_chars: int) -> list[dict[str, str | int]]:
+    return _preview(text, context_chars)
 
-def add_dict(dictionary):
-    for ts in replacers.values():
-        ts.add(dictionary)
-    ts_view_window.add(list(dictionary.keys()))
 
+def add(contraction: str, expansion: str) -> None:
+    return add_custom_contraction(contraction, expansion)
 
-def load_json(filepath):
-    with open(filepath, encoding="utf-8") as f:
-        data = json.load(f)
-    add_dict(data)
 
+def add_dict(contractions_dict: dict[str, str]) -> None:
+    return add_custom_dict(contractions_dict)
 
-def preview(text, flank):
-    """
-    Return all contractions and their location before fix for manual check. Also provide a viewing window to quickly
-    preview the contractions in the text.
-    :param text: texture.
-    :param flank: int number, control the size of the preview window. The window would be "flank-contraction-flank".
-    :return: preview_items, a list includes all matched contractions and their locations.
-    """
-    if not isinstance(flank, int):
-        raise TypeError("Argument flank must be integer!")
 
-    results = ts_view_window.findall(text)
-    text_len = len(text)
+def load_file(filepath: str) -> None:
+    return load_custom_from_file(filepath)
 
-    return [
-        {
-            "match": result.match,
-            "start": result.start,
-            "end": result.end,
-            "viewing_window": text[max(0, result.start - flank):min(text_len, result.end + flank)]
-        }
-        for result in results
-    ]
+
+e = expand
+p = preview
 

contractions/bootstrap.py

@@ -0,0 +1,17 @@
+from .file_loader import load_dict_data, load_list_data
+from .transformers import build_apostrophe_variants, normalize_apostrophes
+
+
+def load_all_contractions() -> tuple[dict[str, str], dict[str, str], dict[str, str]]:
+    contractions_dict = load_dict_data("contractions_dict.json")
+    leftovers_dict = load_dict_data("leftovers_dict.json")
+    slang_dict = load_dict_data("slang_dict.json")
+    safety_keys = frozenset(load_list_data("safety_keys.json"))
+
+    contractions_dict |= normalize_apostrophes(contractions_dict)
+    leftovers_dict |= normalize_apostrophes(leftovers_dict)
+
+    unsafe_dict = build_apostrophe_variants(contractions_dict, safety_keys)
+    slang_dict.update(unsafe_dict)
+
+    return contractions_dict, leftovers_dict, slang_dict