smith-utils 0.1.0__tar.gz

smith_utils-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eiichi YAMAMOTO 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in  
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  
+IN THE SOFTWARE.

smith_utils-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: smith-utils
+Version: 0.1.0
+Summary: A utility library for data cleaning and parsing.
+Author-email: Eiichi YAMAMOTO <info@yeiichi.com>
+License: MIT License
+        
+        Copyright (c) 2026 Eiichi YAMAMOTO 
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights  
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+        copies of the Software, and to permit persons to whom the Software is  
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in  
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  
+        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  
+        IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/yeiichi/smith-utils
+Project-URL: Repository, https://github.com/yeiichi/smith-utils
+Keywords: csv,deduplication,data-filtering,file-organization,filtering
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=8; extra == "docs"
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Dynamic: license-file
+
+# smith-utils
+[![PyPI version](https://img.shields.io/pypi/v/smith-utils.svg)](https://pypi.org/project/smith-utils/)
+![Python versions](https://img.shields.io/pypi/pyversions/smith-utils.svg)
+![Status](https://img.shields.io/badge/status-Alpha-orange.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
+[![Documentation Status](https://readthedocs.org/projects/smith-utils/badge/?version=latest)](https://smith-utils.readthedocs.io/en/latest/?badge=latest)
+
+
+**Smith Utils** is a central hub for data cleaning and parsing scripts. 
+This package consolidates distributed utility functions to improve code reuse and maintenance efficiency across all yeiichi projects.
+
+## Key Features
+
+### 📅 Datetime Utilities (`smith_utils.datetime`)
+Robust date parsing and formatting.
+- `ensure_date`: Flexible conversion of strings, `datetime.date` objects, or `None` (returns today) into a `date` object.
+- `parse_strict_date`: Strict parsing for `YYYYMMDD` or `YYYY-MM-DD` formats, rejecting ambiguous inputs.
+- `format_ordinal`: Converts integers to ordinal strings (e.g., `1` → `"1st"`, `22` → `"22nd"`).
+
+### 🔢 Numeric Refinement (`smith_utils.numeric`)
+Clean and parse messy numeric data.
+- `parse_numeric_value`: Handles custom separators, decimals, and negative formats like `(1,234.56)`.
+- `parse_currency_value`: Alias for numeric parsing, specifically for currency strings.
+
+### 📝 Text Normalization & Metrics (`smith_utils.text`)
+Standardize text and compare string similarity.
+- `normalize_text`: Unicode NFKC normalization, case folding, and whitespace handling.
+- `StringDistance`: Implementation of Damerau-Levenshtein and Jaro-Winkler algorithms for fuzzy matching.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install smith-utils
+```
+
+## Quick Start
+
+```python
+from smith_utils.datetime.date_utils import ensure_date
+from smith_utils.numeric.refinement import parse_numeric_value
+from smith_utils.text.normalization import normalize_text
+
+# Datetime
+date = ensure_date("20231225") # datetime.date(2023, 12, 25)
+
+# Numeric
+value = parse_numeric_value("(1,250.50)") # -1250.5
+
+# Text
+clean_text = normalize_text("  Ｓｍｉｔｈ  Ｕｔｉｌｓ  ") # "smith utils"
+```
+
+## Directory Structure
+- `src/smith_utils/`: Main package source.
+- `legacy/`: Legacy scripts and templates (not included in distribution).
+- `tests/`: Comprehensive test suite.
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

smith_utils-0.1.0/README.md

@@ -0,0 +1,62 @@
+# smith-utils
+[![PyPI version](https://img.shields.io/pypi/v/smith-utils.svg)](https://pypi.org/project/smith-utils/)
+![Python versions](https://img.shields.io/pypi/pyversions/smith-utils.svg)
+![Status](https://img.shields.io/badge/status-Alpha-orange.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
+[![Documentation Status](https://readthedocs.org/projects/smith-utils/badge/?version=latest)](https://smith-utils.readthedocs.io/en/latest/?badge=latest)
+
+
+**Smith Utils** is a central hub for data cleaning and parsing scripts. 
+This package consolidates distributed utility functions to improve code reuse and maintenance efficiency across all yeiichi projects.
+
+## Key Features
+
+### 📅 Datetime Utilities (`smith_utils.datetime`)
+Robust date parsing and formatting.
+- `ensure_date`: Flexible conversion of strings, `datetime.date` objects, or `None` (returns today) into a `date` object.
+- `parse_strict_date`: Strict parsing for `YYYYMMDD` or `YYYY-MM-DD` formats, rejecting ambiguous inputs.
+- `format_ordinal`: Converts integers to ordinal strings (e.g., `1` → `"1st"`, `22` → `"22nd"`).
+
+### 🔢 Numeric Refinement (`smith_utils.numeric`)
+Clean and parse messy numeric data.
+- `parse_numeric_value`: Handles custom separators, decimals, and negative formats like `(1,234.56)`.
+- `parse_currency_value`: Alias for numeric parsing, specifically for currency strings.
+
+### 📝 Text Normalization & Metrics (`smith_utils.text`)
+Standardize text and compare string similarity.
+- `normalize_text`: Unicode NFKC normalization, case folding, and whitespace handling.
+- `StringDistance`: Implementation of Damerau-Levenshtein and Jaro-Winkler algorithms for fuzzy matching.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install smith-utils
+```
+
+## Quick Start
+
+```python
+from smith_utils.datetime.date_utils import ensure_date
+from smith_utils.numeric.refinement import parse_numeric_value
+from smith_utils.text.normalization import normalize_text
+
+# Datetime
+date = ensure_date("20231225") # datetime.date(2023, 12, 25)
+
+# Numeric
+value = parse_numeric_value("(1,250.50)") # -1250.5
+
+# Text
+clean_text = normalize_text("  Ｓｍｉｔｈ  Ｕｔｉｌｓ  ") # "smith utils"
+```
+
+## Directory Structure
+- `src/smith_utils/`: Main package source.
+- `legacy/`: Legacy scripts and templates (not included in distribution).
+- `tests/`: Comprehensive test suite.
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

smith_utils-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smith-utils"
+version = "0.1.0"
+description = "A utility library for data cleaning and parsing."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+
+authors = [
+  { name = "Eiichi YAMAMOTO", email = "info@yeiichi.com" }
+]
+
+keywords = [
+  "csv",
+  "deduplication",
+  "data-filtering",
+  "file-organization",
+  "filtering",
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Utilities",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+docs = [
+  "sphinx>=8,<9",
+  "furo>=2024.8.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/yeiichi/smith-utils"
+Repository = "https://github.com/yeiichi/smith-utils"
+
+[tool.setuptools.packages.find]
+where = ["src"]

smith_utils-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smith_utils-0.1.0/src/smith_utils/__init__.py

@@ -0,0 +1,14 @@
+from .numeric import parse_numeric_value, parse_currency_value
+from .text import StringDistance, analyze_pair, normalize_text
+from .datetime import format_ordinal, parse_strict_date, ensure_date
+
+__all__ = [
+    "parse_numeric_value",
+    "parse_currency_value",
+    "StringDistance",
+    "analyze_pair",
+    "normalize_text",
+    "format_ordinal",
+    "parse_strict_date",
+    "ensure_date",
+]

smith_utils-0.1.0/src/smith_utils/datetime/__init__.py

@@ -0,0 +1,7 @@
+from .date_utils import format_ordinal, parse_strict_date, ensure_date
+
+__all__ = [
+    "format_ordinal",
+    "parse_strict_date",
+    "ensure_date",
+]

smith_utils-0.1.0/src/smith_utils/datetime/date_utils.py

@@ -0,0 +1,111 @@
+# src/calendar_smith/utils.py
+import datetime
+import re
+
+DATE_FORMAT_BASIC = "%Y%m%d"
+DATE_FORMAT_EXTENDED = "%Y-%m-%d"
+
+
+def format_ordinal(n: int) -> str:
+    """
+    Converts an integer to its ordinal representation as a string.
+
+    The function takes an integer input and returns the ordinal form of the 
+    number as a string with its appropriate suffix. For example, 1 becomes 
+    "1st", 2 becomes "2nd", and so on. The suffix rules account for the 
+    exceptional cases such as numbers ending in 11, 12, or 13.
+
+    Args:
+        n (int): The integer to be converted to its ordinal equivalent.
+
+    Returns:
+        str: The ordinal representation of the input number.
+    """
+    if 11 <= (abs(n) % 100) <= 13:
+        suffix = 'th'
+    else:
+        suffix = {1: 'st', 2: 'nd', 3: 'rd'}.get(abs(n) % 10, 'th')
+    return f"{n}{suffix}"
+
+
+def parse_strict_date(date_str: str) -> datetime.date:
+    """
+    Parses a given date string into a `datetime.date` object.
+
+    This function attempts to parse the input date string in various formats
+    while adhering to strict expectations for valid date representations. It 
+    supports both basic (YYYYMMDD) and extended (YYYY-MM-DD) formats and rejects 
+    ambiguous or malformed inputs. The function raises an error if the provided 
+    string does not conform to the acceptable formats.
+
+    Note:
+        The returned `datetime.date` object is naive and does not retain any time zone 
+        information. If the input string contains a time component or time zone 
+        identifier (e.g., after a 'T' or space), it is simply discarded without any 
+        time zone conversion. This means a UTC timestamp might represent a different 
+        calendar date in a local time zone.
+
+    Parameters:
+        date_str (str): The date string to be parsed. It is expected to be in either
+            basic (YYYYMMDD) or extended (YYYY-MM-DD) format.
+
+    Returns:
+        datetime.date: A `date` object representing the parsed date.
+
+    Raises:
+        ValueError: If the input string contains an ambiguous or invalid date.
+    """
+    date_part = date_str.split('T')[0].split(' ')[0]
+    digits_only = re.sub(r'[^0-9]', '', date_part)
+
+    if len(digits_only) == 8 and date_part.isdigit():
+        return datetime.datetime.strptime(digits_only, DATE_FORMAT_BASIC).date()
+
+    if '-' in date_part:
+        try:
+            return datetime.datetime.strptime(date_part, DATE_FORMAT_EXTENDED).date()
+        except ValueError:
+            pass
+
+    if len(digits_only) in (6, 7) or (re.match(r'^\d{1,2}-\d{1,2}$', date_part)):
+        raise ValueError(
+            f"Ambiguous date '{date_str}' rejected. "
+            "Please use 8-digit YYYYMMDD or delimiters (YYYY-MM-DD)."
+        )
+    raise ValueError(f"Could not parse '{date_str}'. Expected YYYY-MM-DD or YYYYMMDD.")
+
+
+def ensure_date(date_input: str | datetime.date | None) -> datetime.date:
+    """
+    Converts various date input formats into a `datetime.date` object.
+
+    This function accepts a string, a `datetime.date` object, or a `None` 
+    value to produce a `datetime.date` object. If the input is `None`, the 
+    current date is returned. String inputs are first stripped of leading 
+    and trailing whitespace, and the function attempts to parse the string 
+    as an ISO 8601 formatted date. If the ISO 8601 parsing fails, the input 
+    is passed to a fallback parsing function for stricter date parsing.
+
+    Raises:
+        ValueError: If the input string cannot be parsed into a valid date 
+        via both ISO 8601 and the fallback parsing mechanism.
+
+    Parameters:
+        date_input (str | datetime.date | None): The input to be converted 
+        to a `datetime.date` object. This can be a string representing a 
+        date, a `datetime.date` object itself, or `None`.
+
+    Returns:
+        datetime.date: A valid `datetime.date` object corresponding to the 
+        provided input, or the current date if the input is `None`.
+    """
+    if not date_input:
+        return datetime.date.today()
+    if isinstance(date_input, datetime.date):
+        return date_input
+
+    clean_input = str(date_input).strip()
+    try:
+        return datetime.date.fromisoformat(clean_input)
+    except ValueError:
+        return parse_strict_date(clean_input)

smith_utils-0.1.0/src/smith_utils/numeric/__init__.py

@@ -0,0 +1,6 @@
+from .refinement import parse_numeric_value, parse_currency_value
+
+__all__ = [
+    "parse_numeric_value",
+    "parse_currency_value",
+]

smith_utils-0.1.0/src/smith_utils/numeric/refinement.py

@@ -0,0 +1,55 @@
+def parse_numeric_value(val: str | float | None, sep: str = ",", decimal: str = ".", relaxed: bool = False) -> float | str:
+    if val is None:
+        return 0.0
+
+    s = str(val).strip()
+    is_negative = False
+
+    if s.startswith("-"):
+        is_negative = True
+        s = s[1:].strip()
+    elif s.startswith("(") and s.endswith(")"):
+        is_negative = True
+        s = s[1:-1].strip()
+
+    # Split by decimal to validate groups
+    parts = s.split(decimal)
+    if len(parts) > 2:
+        if relaxed:
+            return val
+        raise ValueError(f"Invalid numeric value: '{val}'")
+
+    # Validate integer part groups if 'sep' is used
+    int_part = parts[0]
+    if sep in int_part:
+        groups = int_part.split(sep)
+        # All groups except the first must be exactly 3 digits
+        # This is a common rule for thousand separators
+        if any(len(g) != 3 for g in groups[1:]):
+            if relaxed:
+                return val
+            raise ValueError(f"Invalid numeric value: '{val}'")
+
+    s_cleaned = s.replace(sep, "")
+    if decimal != ".":
+        s_cleaned = s_cleaned.replace(decimal, ".")
+
+    try:
+        # Check if separator appears after decimal
+        if sep in s and decimal in s and s.rfind(sep) > s.find(decimal):
+            raise ValueError
+
+        num = float(s_cleaned)
+        # Check if it was purely digits + decimal
+        if not s_cleaned.replace(".", "", 1).isdigit():
+            raise ValueError
+
+        return -num if is_negative else num
+    except ValueError:
+        if relaxed:
+            return val
+        raise ValueError(f"Invalid numeric value: '{val}'")
+
+
+def parse_currency_value(val: str | float | None, sep: str = ",", decimal: str = ".", relaxed: bool = False) -> float | str:
+    return parse_numeric_value(val, sep=sep, decimal=decimal, relaxed=relaxed)

smith_utils-0.1.0/src/smith_utils/text/__init__.py

@@ -0,0 +1,10 @@
+from .metrics import StringDistance, analyze_pair, Result, Relation
+from .normalization import normalize_text
+
+__all__ = [
+    "StringDistance",
+    "analyze_pair",
+    "Result",
+    "Relation",
+    "normalize_text",
+]

smith_utils-0.1.0/src/smith_utils/text/metrics.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class Relation(Enum):
+    EXACT_MATCH = auto()
+    CASE_INSENSITIVE_MATCH = auto()
+    WHITESPACE_TRIMMED_MATCH = auto()
+    NORMALIZED_SPACE_MATCH = auto()
+    NO_STRUCTURAL_MATCH = auto()
+
+
+@dataclass
+class Result:
+    """
+    Represents the result of a comparison, encapsulating classification and similarity metrics.
+
+    This class encapsulates the result of a comparison operation between two entities,
+    including their relationship classification and various similarity metrics. It provides
+    a method to retrieve a string representation of the relationship classification.
+    """
+    classification: Relation
+    damerau_levenshtein_distance: int
+    jaro_winkler_score: float
+    similarity_percentage: float
+
+    def get_relation_string(self) -> str:
+        if self.classification is Relation.EXACT_MATCH:
+            return "Identical"
+        if self.classification is Relation.CASE_INSENSITIVE_MATCH:
+            return "Case-Insensitive Match"
+        if self.classification is Relation.WHITESPACE_TRIMMED_MATCH:
+            return "Similar (Trimmed)"
+        if self.classification is Relation.NORMALIZED_SPACE_MATCH:
+            return "Synonymous (No Spaces)"
+        return "Different"
+
+
+class StringDistance:
+    """
+    Provides functionality for calculating string distances and relationships between
+    two strings based on various algorithms.
+
+    This class includes methods for analyzing string similarities and relationships,
+    including exact matches, case-insensitive comparisons, and whitespace normalization.
+    It also implements Damerau-Levenshtein and Jaro-Winkler distance calculations.
+
+    :return classification: Possible relationship classification between two strings.
+    :return damerau_levenshtein_distance: Integer distance calculated using the Damerau-Levenshtein algorithm.
+    :return jaro_winkler_score: A float score indicating similarity using the Jaro-Winkler algorithm.
+    :return similarity_percentage: A percentage similarity score between two strings.
+    """
+    @staticmethod
+    def analyze(a: str, b: str, ignore_case: bool = False) -> Result:
+        sa = str(a)
+        sb = str(b)
+
+        relation = StringDistance.classify(sa, sb)
+
+        if ignore_case:
+            sa = sa.lower()
+            sb = sb.lower()
+
+        d_dist = StringDistance.calculate_damerau_levenshtein(sa, sb)
+        jw_score = StringDistance.calculate_jaro_winkler(sa, sb)
+
+        max_len = max(len(sa), len(sb))
+        similarity = 100.0 if max_len == 0 else (1.0 - d_dist / max_len) * 100.0
+
+        return Result(
+            classification=relation,
+            damerau_levenshtein_distance=d_dist,
+            jaro_winkler_score=jw_score,
+            similarity_percentage=similarity,
+        )
+
+    @staticmethod
+    def trim(s: str) -> str:
+        return s.strip()
+
+    @staticmethod
+    def strip_all(s: str) -> str:
+        """
+        Remove all whitespace characters from a string.
+
+        Uses split/join logic so any whitespace character acts as a separator,
+        including spaces, tabs, and newlines.
+        """
+        return "".join(s.split())
+
+    @staticmethod
+    def equals_ignore_case(a: str, b: str) -> bool:
+        return a.lower() == b.lower()
+
+    @staticmethod
+    def classify(a: str, b: str) -> Relation:
+        if a == b:
+            return Relation.EXACT_MATCH
+        if StringDistance.equals_ignore_case(a, b):
+            return Relation.CASE_INSENSITIVE_MATCH
+        if StringDistance.trim(a) == StringDistance.trim(b):
+            return Relation.WHITESPACE_TRIMMED_MATCH
+        if StringDistance.strip_all(a) == StringDistance.strip_all(b):
+            return Relation.NORMALIZED_SPACE_MATCH
+        return Relation.NO_STRUCTURAL_MATCH
+
+    @staticmethod
+    def calculate_damerau_levenshtein(s1: str, s2: str) -> int:
+        """
+        Restricted Damerau-Levenshtein distance:
+        insertion, deletion, substitution, adjacent transposition.
+        """
+        m = len(s1)
+        n = len(s2)
+
+        d = [[0] * (n + 1) for _ in range(m + 1)]
+
+        for i in range(m + 1):
+            d[i][0] = i
+        for j in range(n + 1):
+            d[0][j] = j
+
+        for i in range(1, m + 1):
+            for j in range(1, n + 1):
+                cost = 0 if s1[i - 1] == s2[j - 1] else 1
+
+                d[i][j] = min(
+                    d[i - 1][j] + 1,        # deletion
+                    d[i][j - 1] + 1,        # insertion
+                    d[i - 1][j - 1] + cost, # substitution
+                )
+
+                if (
+                    i > 1
+                    and j > 1
+                    and s1[i - 1] == s2[j - 2]
+                    and s1[i - 2] == s2[j - 1]
+                ):
+                    d[i][j] = min(d[i][j], d[i - 2][j - 2] + cost)
+
+        return d[m][n]
+
+    @staticmethod
+    def calculate_jaro_winkler(s1: str, s2: str) -> float:
+        len1 = len(s1)
+        len2 = len(s2)
+
+        if len1 == 0 and len2 == 0:
+            return 1.0
+        if len1 == 0 or len2 == 0:
+            return 0.0
+
+        match_distance = max(len1, len2) // 2 - 1
+        if match_distance < 0:
+            match_distance = 0
+
+        s1_matches = [False] * len1
+        s2_matches = [False] * len2
+
+        matches = 0
+        for i in range(len1):
+            start = max(0, i - match_distance)
+            end = min(i + match_distance + 1, len2)
+
+            for j in range(start, end):
+                if not s2_matches[j] and s1[i] == s2[j]:
+                    s1_matches[i] = True
+                    s2_matches[j] = True
+                    matches += 1
+                    break
+
+        if matches == 0:
+            return 0.0
+
+        transpositions = 0
+        k = 0
+        for i in range(len1):
+            if s1_matches[i]:
+                while not s2_matches[k]:
+                    k += 1
+                if s1[i] != s2[k]:
+                    transpositions += 1
+                k += 1
+
+        jaro = (
+            matches / len1
+            + matches / len2
+            + (matches - transpositions / 2.0) / matches
+        ) / 3.0
+
+        p = 0.1
+        max_l = 4
+        l = 0
+        while l < min(len1, len2, max_l) and s1[l] == s2[l]:
+            l += 1
+
+        return jaro + (l * p * (1.0 - jaro))
+
+
+def analyze_pair(a: str, b: str, ignore_case: bool = False) -> Result:
+    return StringDistance.analyze(a, b, ignore_case)

smith_utils-0.1.0/src/smith_utils/text/normalization.py

@@ -0,0 +1,43 @@
+import unicodedata
+
+
+def normalize_text(text, ignore_case=True, remove_all_whitespace=False, nfkc=True):
+    """
+    Normalizes the input text by applying transformations such as Unicode normalization,
+    case folding, and whitespace handling.
+
+    Parameters:
+        text (str or None): The input text to normalize_text. If None, an empty string is returned.
+        ignore_case (bool, optional): Whether to convert the text to lowercase. Defaults to True.
+        remove_all_whitespace (bool, optional): Whether to remove all internal whitespace and trim outer
+            whitespace. Defaults to False.
+        nfkc (bool, optional): Whether to apply Unicode normalization using NFKC form. Defaults to
+            True.
+
+    Returns:
+        str: The normalized text.
+    """
+    if text is None:
+        return ""
+
+    # Cast to string to handle numeric cells safely
+    text = str(text)
+
+    # 1. Unicode Compatibility (Handles full-width/ligatures)
+    if nfkc:
+        text = unicodedata.normalize('NFKC', text)
+
+    # 3. Whitespace handling
+    # Always trim outer whitespace, and optionally remove all internal whitespace.
+    text = text.strip()
+    if remove_all_whitespace:
+        text = "".join(text.split())
+    else:
+        # Note: join(split()) reduces multiple spaces to one.
+        text = " ".join(text.split())
+
+    # 2. Case Folding
+    if ignore_case:
+        text = text.lower()
+
+    return text

smith_utils-0.1.0/src/smith_utils.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: smith-utils
+Version: 0.1.0
+Summary: A utility library for data cleaning and parsing.
+Author-email: Eiichi YAMAMOTO <info@yeiichi.com>
+License: MIT License
+        
+        Copyright (c) 2026 Eiichi YAMAMOTO 
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights  
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+        copies of the Software, and to permit persons to whom the Software is  
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in  
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  
+        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS  
+        IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/yeiichi/smith-utils
+Project-URL: Repository, https://github.com/yeiichi/smith-utils
+Keywords: csv,deduplication,data-filtering,file-organization,filtering
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=8; extra == "docs"
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Dynamic: license-file
+
+# smith-utils
+[![PyPI version](https://img.shields.io/pypi/v/smith-utils.svg)](https://pypi.org/project/smith-utils/)
+![Python versions](https://img.shields.io/pypi/pyversions/smith-utils.svg)
+![Status](https://img.shields.io/badge/status-Alpha-orange.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
+[![Documentation Status](https://readthedocs.org/projects/smith-utils/badge/?version=latest)](https://smith-utils.readthedocs.io/en/latest/?badge=latest)
+
+
+**Smith Utils** is a central hub for data cleaning and parsing scripts. 
+This package consolidates distributed utility functions to improve code reuse and maintenance efficiency across all yeiichi projects.
+
+## Key Features
+
+### 📅 Datetime Utilities (`smith_utils.datetime`)
+Robust date parsing and formatting.
+- `ensure_date`: Flexible conversion of strings, `datetime.date` objects, or `None` (returns today) into a `date` object.
+- `parse_strict_date`: Strict parsing for `YYYYMMDD` or `YYYY-MM-DD` formats, rejecting ambiguous inputs.
+- `format_ordinal`: Converts integers to ordinal strings (e.g., `1` → `"1st"`, `22` → `"22nd"`).
+
+### 🔢 Numeric Refinement (`smith_utils.numeric`)
+Clean and parse messy numeric data.
+- `parse_numeric_value`: Handles custom separators, decimals, and negative formats like `(1,234.56)`.
+- `parse_currency_value`: Alias for numeric parsing, specifically for currency strings.
+
+### 📝 Text Normalization & Metrics (`smith_utils.text`)
+Standardize text and compare string similarity.
+- `normalize_text`: Unicode NFKC normalization, case folding, and whitespace handling.
+- `StringDistance`: Implementation of Damerau-Levenshtein and Jaro-Winkler algorithms for fuzzy matching.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install smith-utils
+```
+
+## Quick Start
+
+```python
+from smith_utils.datetime.date_utils import ensure_date
+from smith_utils.numeric.refinement import parse_numeric_value
+from smith_utils.text.normalization import normalize_text
+
+# Datetime
+date = ensure_date("20231225") # datetime.date(2023, 12, 25)
+
+# Numeric
+value = parse_numeric_value("(1,250.50)") # -1250.5
+
+# Text
+clean_text = normalize_text("  Ｓｍｉｔｈ  Ｕｔｉｌｓ  ") # "smith utils"
+```
+
+## Directory Structure
+- `src/smith_utils/`: Main package source.
+- `legacy/`: Legacy scripts and templates (not included in distribution).
+- `tests/`: Comprehensive test suite.
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

smith_utils-0.1.0/src/smith_utils.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/smith_utils/__init__.py
+src/smith_utils.egg-info/PKG-INFO
+src/smith_utils.egg-info/SOURCES.txt
+src/smith_utils.egg-info/dependency_links.txt
+src/smith_utils.egg-info/requires.txt
+src/smith_utils.egg-info/top_level.txt
+src/smith_utils/datetime/__init__.py
+src/smith_utils/datetime/date_utils.py
+src/smith_utils/numeric/__init__.py
+src/smith_utils/numeric/refinement.py
+src/smith_utils/text/__init__.py
+src/smith_utils/text/metrics.py
+src/smith_utils/text/normalization.py
+tests/test_date_utils.py
+tests/test_metrics.py
+tests/test_normalization.py
+tests/test_refinement.py

smith_utils-0.1.0/src/smith_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

smith_utils-0.1.0/src/smith_utils.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[docs]
+sphinx<9,>=8
+furo>=2024.8.6

smith_utils-0.1.0/src/smith_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+smith_utils

smith_utils-0.1.0/tests/test_date_utils.py

@@ -0,0 +1,68 @@
+import datetime
+
+import pytest
+
+from src.smith_utils.datetime.date_utils import format_ordinal, parse_strict_date
+
+
+def test_format_ordinal_single_digits():
+    assert format_ordinal(1) == "1st"
+    assert format_ordinal(2) == "2nd"
+    assert format_ordinal(3) == "3rd"
+    assert format_ordinal(4) == "4th"
+    assert format_ordinal(9) == "9th"
+
+
+def test_format_ordinal_double_digits():
+    assert format_ordinal(11) == "11th"
+    assert format_ordinal(12) == "12th"
+    assert format_ordinal(13) == "13th"
+    assert format_ordinal(21) == "21st"
+    assert format_ordinal(22) == "22nd"
+
+
+def test_format_ordinal_large_numbers():
+    assert format_ordinal(100) == "100th"
+    assert format_ordinal(111) == "111th"
+    assert format_ordinal(112) == "112th"
+    assert format_ordinal(113) == "113th"
+    assert format_ordinal(121) == "121st"
+
+
+def test_format_ordinal_negative_numbers():
+    assert format_ordinal(-1) == "-1st"
+    assert format_ordinal(-2) == "-2nd"
+    assert format_ordinal(-3) == "-3rd"
+    assert format_ordinal(-11) == "-11th"
+    assert format_ordinal(-22) == "-22nd"
+
+
+def test_format_ordinal_edge_cases():
+    assert format_ordinal(0) == "0th"
+    assert format_ordinal(1000) == "1000th"
+
+
+def test_parse_strict_date_basic_format():
+    assert parse_strict_date("20260413") == datetime.date(2026, 4, 13)
+    assert parse_strict_date("19991231") == datetime.date(1999, 12, 31)
+
+
+def test_parse_strict_date_extended_format():
+    assert parse_strict_date("2026-04-13") == datetime.date(2026, 4, 13)
+    assert parse_strict_date("1999-12-31") == datetime.date(1999, 12, 31)
+
+
+def test_parse_strict_date_invalid_formats():
+    with pytest.raises(ValueError, match="Could not parse '13-04-2026'. Expected YYYY-MM-DD or YYYYMMDD."):
+        parse_strict_date("13-04-2026")
+
+    with pytest.raises(ValueError, match="Could not parse '2026/04/13'. Expected YYYY-MM-DD or YYYYMMDD."):
+        parse_strict_date("2026/04/13")
+
+
+def test_parse_strict_date_ambiguous_inputs():
+    with pytest.raises(ValueError, match=r"Ambiguous date '2026413' rejected\. .*"):
+        parse_strict_date("2026413")
+
+    with pytest.raises(ValueError, match="Ambiguous date '06-13' rejected. .*"):
+        parse_strict_date("06-13")

smith_utils-0.1.0/tests/test_metrics.py

@@ -0,0 +1,74 @@
+# tests/test_metrics.py
+
+from src.smith_utils.text.metrics import StringDistance, Relation, Result
+
+
+def test_equals_ignore_case():
+    assert StringDistance.equals_ignore_case("Test", "test")
+    assert StringDistance.equals_ignore_case("TEST", "test")
+    assert not StringDistance.equals_ignore_case("Test", "Another")
+
+
+def test_trim():
+    assert StringDistance.trim("  hello  ") == "hello"
+    assert StringDistance.trim("\t\ttest\t") == "test"
+    assert StringDistance.trim("no_spaces") == "no_spaces"
+
+
+def test_strip_all():
+    assert StringDistance.strip_all("  he  llo  ") == "hello"
+    assert StringDistance.strip_all("\t\tt e\ts\tt\t") == "test"
+    assert StringDistance.strip_all("no   spaces\t") == "nospaces"
+
+
+def test_classify_exact_match():
+    result = StringDistance.classify("hello", "hello")
+    assert result == Relation.EXACT_MATCH
+
+
+def test_classify_case_insensitive_match():
+    result = StringDistance.classify("HELLO", "hello")
+    assert result == Relation.CASE_INSENSITIVE_MATCH
+
+
+def test_classify_whitespace_trimmed_match():
+    result = StringDistance.classify("  hello  ", "hello")
+    assert result == Relation.WHITESPACE_TRIMMED_MATCH
+
+
+def test_classify_normalized_space_match():
+    result = StringDistance.classify("he llo", "hel lo")
+    assert result == Relation.NORMALIZED_SPACE_MATCH
+
+
+def test_classify_no_structural_match():
+    result = StringDistance.classify("hello", "world")
+    assert result == Relation.NO_STRUCTURAL_MATCH
+
+
+def test_analyze_similarity_metrics_case_insensitive():
+    result = StringDistance.analyze("HELLO", "hello", ignore_case=True)
+    assert isinstance(result, Result)
+    assert result.classification == Relation.CASE_INSENSITIVE_MATCH
+    assert result.damerau_levenshtein_distance == 0
+    assert result.jaro_winkler_score > 0.9
+    assert result.similarity_percentage == 100.0
+
+
+def test_calculate_damerau_levenshtein():
+    distance = StringDistance.calculate_damerau_levenshtein("kitten", "sitting")
+    assert distance == 3
+
+
+def test_calculate_jaro_winkler():
+    score = StringDistance.calculate_jaro_winkler("MARTHA", "MARHTA")
+    assert score > 0.9
+
+
+def test_analyze_empty_strings():
+    result = StringDistance.analyze("", "", ignore_case=False)
+    assert isinstance(result, Result)
+    assert result.classification == Relation.EXACT_MATCH
+    assert result.damerau_levenshtein_distance == 0
+    assert result.jaro_winkler_score == 1.0
+    assert result.similarity_percentage == 100.0

smith_utils-0.1.0/tests/test_normalization.py

@@ -0,0 +1,43 @@
+from src.smith_utils.text.normalization import normalize_text
+
+
+def test_normalize_none_input():
+    assert normalize_text(None) == ""
+
+
+def test_normalize_empty_string():
+    assert normalize_text("") == ""
+
+
+def test_normalize_whitespaces_only():
+    assert normalize_text("   ") == ""
+
+
+def test_normalize_lowercase_conversion():
+    result = normalize_text("Hello World")
+    assert result == "hello world"
+
+
+def test_normalize_unicodedata_nfkc():
+    result = normalize_text(u"① Ⅱ Ⅲ")
+    assert result == "1 ii iii"
+
+
+def test_normalize_remove_all_whitespace():
+    result = normalize_text(" Hello   World ", ignore_case=False, remove_all_whitespace=True)
+    assert result == "HelloWorld"
+
+
+def test_normalize_trim_whitespace():
+    result = normalize_text("   Hello World   ")
+    assert result == "hello world"
+
+
+def test_normalize_nfkc_and_case_fold():
+    result = normalize_text(u"①ＡＢＣ def")
+    assert result == "1abc def"
+
+
+def test_normalize_case_sensitive_option():
+    result = normalize_text("Hello World", ignore_case=False)
+    assert result == "Hello World"

smith_utils-0.1.0/tests/test_refinement.py

@@ -0,0 +1,37 @@
+# tests/test_refinement.py
+
+import pytest
+from src.smith_utils.numeric.refinement import parse_numeric_value
+
+
+def test_clean_numeric_valid_input():
+    assert parse_numeric_value("1,234.56") == 1234.56
+    assert parse_numeric_value("1234.56") == 1234.56
+    assert parse_numeric_value("1 234.56", sep=" ") == 1234.56
+
+
+def test_clean_numeric_invalid_input_raises_error():
+    with pytest.raises(ValueError):
+        parse_numeric_value("invalid")
+    with pytest.raises(ValueError):
+        parse_numeric_value("1234,56.78")
+
+
+def test_clean_numeric_relaxed_mode_invalid_input():
+    assert parse_numeric_value("invalid", relaxed=True) == "invalid"
+    assert parse_numeric_value("1234,56.78", relaxed=True) == "1234,56.78"
+
+
+def test_clean_numeric_none_value():
+    assert parse_numeric_value(None) == 0.0
+
+
+def test_clean_numeric_with_custom_separators():
+    assert parse_numeric_value("1.234,56", sep=".", decimal=",") == 1234.56
+    assert parse_numeric_value("1 234,56", sep=" ", decimal=",") == 1234.56
+
+
+def test_clean_numeric_negative_number():
+    assert parse_numeric_value("-1234.56") == -1234.56
+    assert parse_numeric_value("(1234.56)") == -1234.56
+    assert parse_numeric_value("(1,234.56)") == -1234.56