convi-lab 0.1.0__tar.gz

convi_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mosquito-Lab
+
+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.

convi_lab-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: convi-lab
+Version: 0.1.0
+Summary: Data conversion/normalization in a nutshell
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: logger-lab>=0.1.1
+Requires-Dist: rapidfuzz>=3.0.0
+Dynamic: license-file
+
+# convi-lab
+
+Data conversion and normalization utilities. The current focus is datetime
+parsing — turning messily formatted date/time strings into a single
+normalized `"YYYY-MM-DD HH:MM:SS"` output — with fuzzy name matching as a
+first-class primitive that powers the date logic and is exposed for general use.
+
+---
+
+## Installation
+
+```bash
+pip install convi-lab
+```
+
+**Runtime dependencies:** `logger-lab >= 0.1.1`, `rapidfuzz >= 3.0.0`
+
+---
+
+## Quick start
+
+```python
+from convi_lab import convert_date_time, convert_name, DAYS, MONTHS
+
+# Datetime normalization
+convert_date_time("Tuesday 12:30 PM")      # "2026-05-13 12:30:00"
+convert_date_time("17 Jul - 02:00 PM")     # "2026-07-17 14:00:00"
+convert_date_time("12.04.2025 22:15")      # "2026-04-12 22:15:00"
+convert_date_time("Today 09:00")           # "2026-05-09 09:00:00"
+
+# Fuzzy name matching
+convert_name("Mon",    DAYS)               # "Monday"
+convert_name("Jul",    MONTHS)             # "July"
+convert_name("Celts",  ["Boston Celtics", "Brooklyn Nets"])  # "Boston Celtics"
+```
+
+---
+
+## Supported datetime formats
+
+All formats accept an optional `AM`/`PM` suffix (case-insensitive).
+Spaces between components are stripped automatically.
+
+| Format                 | Example input           | Parsed as            |
+|------------------------|-------------------------|----------------------|
+| `dd/mm HH:MM`          | `"12/04 22:15"`         | April 12, 22:15      |
+| `dd/mm/yy HH:MM`       | `"12/04/25 10:15 PM"`   | April 12 2025, 22:15 |
+| `dd.mm.yyyy HH:MM`     | `"12.04.2025 12:15 pm"` | April 12 2025, 12:15 |
+| `Day HH:MM`            | `"Tuesday 12:30"`       | Next Tuesday, 12:30  |
+| `Today/Tomorrow HH:MM` | `"Today 14:30"`         | Today at 14:30       |
+| `ddMon[-]HH:MM`        | `"17 Jul - 02:00 PM"`   | July 17, 14:00       |
+
+**Year boundary rule:** if the resolved date is in the past (date only,
+not time), the year is automatically bumped to the next calendar year.
+
+**Day rule:** weekday names always resolve to the *next* occurrence. If
+today is Tuesday and you pass `"Tuesday 12:30"`, the result is next
+Tuesday, not today.
+
+---
+
+## Error handling
+
+All exceptions inherit from `LabError`. You can catch broadly or precisely:
+
+```python
+from convi_lab import convert_date_time, LabError, ParserError
+
+# convert_date_time is the safe boundary — it returns "" on any failure
+result = convert_date_time("garbage input")
+assert result == ""
+
+# Call process_patterns directly to get typed exceptions
+from convi_lab import process_patterns
+from convi_lab.conversion_kernel.utils import remove_spaces
+
+try:
+    dt = process_patterns(remove_spaces("17 Jly - 02:00"))
+except ParserError as exc:
+    print(f"Parse failed: {exc}")
+except LabError as exc:
+    print(f"Conversion failed: {exc}")
+```
+
+### Exception hierarchy
+
+```
+LabError
+├── ParserError
+│   ├── PatternMatchError      no pattern matched the input
+│   ├── DayResolutionError     weekday/relative-day string unresolvable
+│   ├── MonthResolutionError   month name unresolvable
+│   └── DateComponentError     numeric date fragment malformed
+└── ConversionError
+    ├── ClockFormatError       HH:MM[AM|PM] string failed to parse
+    ├── FuzzyMatchError        rapidfuzz returned no result
+    └── InvalidInputError      bad type or empty string at entry point
+```
+
+---
+
+## Fuzzy name matching
+
+`convert_name` is a general-purpose utility — pass any query and any
+reference list:
+
+```python
+from convi_lab import convert_name
+
+teams = ["Atlanta Hawks", "Boston Celtics", "Brooklyn Nets"]
+convert_name("A. Hawks", teams)   # "Atlanta Hawks"
+convert_name("Nets",     teams)   # "Brooklyn Nets"
+
+countries = ["United States", "United Kingdom", "Australia"]
+convert_name("USA",   countries)  # "United States"
+convert_name("Aus",   countries)  # "Australia"
+```
+
+It raises `FuzzyMatchError` if rapidfuzz finds nothing, so you always
+get a typed failure rather than a silent empty string.
+
+---
+
+## Roadmap
+
+The library is intentionally small today. Planned additions:
+
+### Number and currency
+- **Locale-aware number parsing** — `"1.234,56"` (DE) / `"1,234.56"` (US) → `float`
+- **Currency string normalization** — `"$1,200.00"`, `"€ 1.200"` → `Decimal`
+
+### Identity and contact data
+- **Phone number normalization** — `"+1 (800) 555-0100"`, `"08001234"` → E.164 format
+- **Email normalization** — lowercase, strip display names, validate structure
+- **Name normalization** — `"DR. JOHN A. SMITH"` → `{"prefix": "Dr.", "first": "John", "last": "Smith"}`
+
+### Units and measurements  
+- **Temperature** — `"98.6 F"` / `"37 C"` / `"310 K"` → normalized `(value, unit)`
+- **Distance** — km, miles, nautical miles with conversion helpers
+- **Weight** — kg, lb, oz
+
+### Geolocation
+- **Country/locale normalization** — `"USA"`, `"US"`, `"United States of America"` → ISO 3166-1 alpha-2
+- **Timezone string normalization** — `"EST"`, `"Eastern Time"`, `"America/New_York"` → IANA key
+
+### Data quality
+- **Boolean parsing** — `"yes"`, `"true"`, `"1"`, `"on"`, `"enabled"` → `bool`
+- **Null/empty detection** — `"N/A"`, `"none"`, `"–"`, `""` → `None`
+- **Whitespace and encoding normalization** — strip invisible Unicode, normalize line endings
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

convi_lab-0.1.0/README.md

@@ -0,0 +1,155 @@
+# convi-lab
+
+Data conversion and normalization utilities. The current focus is datetime
+parsing — turning messily formatted date/time strings into a single
+normalized `"YYYY-MM-DD HH:MM:SS"` output — with fuzzy name matching as a
+first-class primitive that powers the date logic and is exposed for general use.
+
+---
+
+## Installation
+
+```bash
+pip install convi-lab
+```
+
+**Runtime dependencies:** `logger-lab >= 0.1.1`, `rapidfuzz >= 3.0.0`
+
+---
+
+## Quick start
+
+```python
+from convi_lab import convert_date_time, convert_name, DAYS, MONTHS
+
+# Datetime normalization
+convert_date_time("Tuesday 12:30 PM")      # "2026-05-13 12:30:00"
+convert_date_time("17 Jul - 02:00 PM")     # "2026-07-17 14:00:00"
+convert_date_time("12.04.2025 22:15")      # "2026-04-12 22:15:00"
+convert_date_time("Today 09:00")           # "2026-05-09 09:00:00"
+
+# Fuzzy name matching
+convert_name("Mon",    DAYS)               # "Monday"
+convert_name("Jul",    MONTHS)             # "July"
+convert_name("Celts",  ["Boston Celtics", "Brooklyn Nets"])  # "Boston Celtics"
+```
+
+---
+
+## Supported datetime formats
+
+All formats accept an optional `AM`/`PM` suffix (case-insensitive).
+Spaces between components are stripped automatically.
+
+| Format                 | Example input           | Parsed as            |
+|------------------------|-------------------------|----------------------|
+| `dd/mm HH:MM`          | `"12/04 22:15"`         | April 12, 22:15      |
+| `dd/mm/yy HH:MM`       | `"12/04/25 10:15 PM"`   | April 12 2025, 22:15 |
+| `dd.mm.yyyy HH:MM`     | `"12.04.2025 12:15 pm"` | April 12 2025, 12:15 |
+| `Day HH:MM`            | `"Tuesday 12:30"`       | Next Tuesday, 12:30  |
+| `Today/Tomorrow HH:MM` | `"Today 14:30"`         | Today at 14:30       |
+| `ddMon[-]HH:MM`        | `"17 Jul - 02:00 PM"`   | July 17, 14:00       |
+
+**Year boundary rule:** if the resolved date is in the past (date only,
+not time), the year is automatically bumped to the next calendar year.
+
+**Day rule:** weekday names always resolve to the *next* occurrence. If
+today is Tuesday and you pass `"Tuesday 12:30"`, the result is next
+Tuesday, not today.
+
+---
+
+## Error handling
+
+All exceptions inherit from `LabError`. You can catch broadly or precisely:
+
+```python
+from convi_lab import convert_date_time, LabError, ParserError
+
+# convert_date_time is the safe boundary — it returns "" on any failure
+result = convert_date_time("garbage input")
+assert result == ""
+
+# Call process_patterns directly to get typed exceptions
+from convi_lab import process_patterns
+from convi_lab.conversion_kernel.utils import remove_spaces
+
+try:
+    dt = process_patterns(remove_spaces("17 Jly - 02:00"))
+except ParserError as exc:
+    print(f"Parse failed: {exc}")
+except LabError as exc:
+    print(f"Conversion failed: {exc}")
+```
+
+### Exception hierarchy
+
+```
+LabError
+├── ParserError
+│   ├── PatternMatchError      no pattern matched the input
+│   ├── DayResolutionError     weekday/relative-day string unresolvable
+│   ├── MonthResolutionError   month name unresolvable
+│   └── DateComponentError     numeric date fragment malformed
+└── ConversionError
+    ├── ClockFormatError       HH:MM[AM|PM] string failed to parse
+    ├── FuzzyMatchError        rapidfuzz returned no result
+    └── InvalidInputError      bad type or empty string at entry point
+```
+
+---
+
+## Fuzzy name matching
+
+`convert_name` is a general-purpose utility — pass any query and any
+reference list:
+
+```python
+from convi_lab import convert_name
+
+teams = ["Atlanta Hawks", "Boston Celtics", "Brooklyn Nets"]
+convert_name("A. Hawks", teams)   # "Atlanta Hawks"
+convert_name("Nets",     teams)   # "Brooklyn Nets"
+
+countries = ["United States", "United Kingdom", "Australia"]
+convert_name("USA",   countries)  # "United States"
+convert_name("Aus",   countries)  # "Australia"
+```
+
+It raises `FuzzyMatchError` if rapidfuzz finds nothing, so you always
+get a typed failure rather than a silent empty string.
+
+---
+
+## Roadmap
+
+The library is intentionally small today. Planned additions:
+
+### Number and currency
+- **Locale-aware number parsing** — `"1.234,56"` (DE) / `"1,234.56"` (US) → `float`
+- **Currency string normalization** — `"$1,200.00"`, `"€ 1.200"` → `Decimal`
+
+### Identity and contact data
+- **Phone number normalization** — `"+1 (800) 555-0100"`, `"08001234"` → E.164 format
+- **Email normalization** — lowercase, strip display names, validate structure
+- **Name normalization** — `"DR. JOHN A. SMITH"` → `{"prefix": "Dr.", "first": "John", "last": "Smith"}`
+
+### Units and measurements  
+- **Temperature** — `"98.6 F"` / `"37 C"` / `"310 K"` → normalized `(value, unit)`
+- **Distance** — km, miles, nautical miles with conversion helpers
+- **Weight** — kg, lb, oz
+
+### Geolocation
+- **Country/locale normalization** — `"USA"`, `"US"`, `"United States of America"` → ISO 3166-1 alpha-2
+- **Timezone string normalization** — `"EST"`, `"Eastern Time"`, `"America/New_York"` → IANA key
+
+### Data quality
+- **Boolean parsing** — `"yes"`, `"true"`, `"1"`, `"on"`, `"enabled"` → `bool`
+- **Null/empty detection** — `"N/A"`, `"none"`, `"–"`, `""` → `None`
+- **Whitespace and encoding normalization** — strip invisible Unicode, normalize line endings
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

convi_lab-0.1.0/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "convi-lab"
+version = "0.1.0"
+description = "Data conversion/normalization in a nutshell"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "logger-lab>=0.1.1",
+    "rapidfuzz>=3.0.0",
+]

convi_lab-0.1.0/setup.cfg

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

convi_lab-0.1.0/src/convi_lab/__init__.py

@@ -0,0 +1,76 @@
+"""
+convi-lab — Data conversion and normalization utilities.
+
+Public API
+----------
+Conversions:
+    convert_to_24_format  – Normalize any time string to 24-hour datetime
+    convert_name          – Fuzzy-match a name against a reference list
+    convert_date_time     – Master entry point: raw string → "YYYY-MM-DD HH:MM:SS"
+
+Parsers (lower-level, used internally by convert_date_time):
+    parse_day_month_time  – "17Jul-02:00PM" style strings
+    parse_day_time        – "Tuesday12:30", "Today14:30" style strings
+    parse_date_time       – "12/04/2522:15", "12.04.202512:15pm" style strings
+
+Errors:
+    LabError              – base; catch this for any convi-lab exception
+    ParserError           – base for all parse-time failures
+    ConversionError       – base for all conversion-time failures
+    PatternMatchError, DayResolutionError, MonthResolutionError, DateComponentError
+    ClockFormatError, FuzzyMatchError, InvalidInputError
+
+Constants / helpers:
+    DAYS, MONTHS, RELATIVE_DAYS, WEEKDAY_MAP, TIME_PATTERNS, TEST_CASES
+    process_patterns
+"""
+
+from convi_lab.conversions import convert_to_24_format, convert_name, convert_date_time
+from convi_lab.parsers import parse_day_month_time, parse_day_time, parse_date_time
+from convi_lab.conversion_kernel.errors import (
+    LabError,
+    ParserError,
+    PatternMatchError,
+    DayResolutionError,
+    MonthResolutionError,
+    DateComponentError,
+    ConversionError,
+    ClockFormatError,
+    FuzzyMatchError,
+    InvalidInputError,
+)
+from convi_lab.conversion_kernel.constants import DAYS, MONTHS, RELATIVE_DAYS, WEEKDAY_MAP, TIME_PATTERNS, TEST_CASES
+from convi_lab.conversion_kernel.pattern_parsers import process_patterns
+
+__all__ = [
+    # Conversions
+    "convert_to_24_format",
+    "convert_name",
+    "convert_date_time",
+    # Parsers
+    "parse_day_month_time",
+    "parse_day_time",
+    "parse_date_time",
+    # Errors — root
+    "LabError",
+    # Errors — parsers
+    "ParserError",
+    "PatternMatchError",
+    "DayResolutionError",
+    "MonthResolutionError",
+    "DateComponentError",
+    # Errors — conversions
+    "ConversionError",
+    "ClockFormatError",
+    "FuzzyMatchError",
+    "InvalidInputError",
+    # Constants
+    "DAYS",
+    "MONTHS",
+    "RELATIVE_DAYS",
+    "WEEKDAY_MAP",
+    "TIME_PATTERNS",
+    "TEST_CASES",
+    # Helpers
+    "process_patterns",
+]

convi_lab-0.1.0/src/convi_lab/conversion_kernel/__init__.py

@@ -0,0 +1,5 @@
+from .pattern_parsers import process_patterns
+
+__all__ = [
+    'process_patterns',
+]

convi_lab-0.1.0/src/convi_lab/conversion_kernel/constants.py

@@ -0,0 +1,123 @@
+import re
+
+###########################
+# Day / month name tables #
+###########################
+
+# All available days for the day time parser
+DAYS = [
+    'Today', 'Tomorrow', 'Monday', 'Tuesday',
+    'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'
+]
+
+# All calendar months for pattern parsers
+MONTHS = [
+    'January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December'
+]
+
+# Relative days specific to parse_relative_time()
+RELATIVE_DAYS = [
+    'Today','Tomorrow'
+]
+
+# Map days to datetime standard
+WEEKDAY_MAP = {
+    "Monday": 0, "Tuesday": 1, "Wednesday": 2, "Thursday": 3,
+    "Friday": 4, "Saturday": 5, "Sunday": 6
+}
+
+###############################################
+# Abbreviation tables (used to build regexes) #
+###############################################
+
+# Day abbreviations
+SHORTFORM_DAYS = [
+    'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'
+]
+
+# Month abbreviations
+SHORTFORM_MONTHS = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+]
+
+# The remaining part of day abbreviations
+SHORTFORM_DAY_ENDERS = [
+    'day', 'sday', 'nesday', 'rsday', 'urday'
+]
+
+
+# The remaining part of month abbreviations
+SHORTFORM_MONTH_ENDERS = [
+    'uary', 'ruary', 'ch', 'il',
+    'y', 'ust', 'tember', 'ober', 'ember',
+    'e'
+]
+
+##########################
+# Atomic regex fragments #
+##########################
+
+# Date regular expressions
+re_num_day = r"^(?:0[0-9]|[12][0-9]|3[01])"
+re_num_month = r"[./](?:0[1-9]|1[0-2])"
+re_year = r"([./]2[5-9]|[./]202[5-9])?"
+
+# Time regular expressions
+re_time = r"((?:[01]?\d|2[0-3]):[0-5]\d)"
+re_am_pm = r"([AaPp][Mm])?$"
+
+######################
+# Compound fragments #
+######################
+
+# Compound regular expressions
+_date_re = rf"({re_num_day}{re_num_month})"
+_day_re = rf"^((?:Today|Tomorrow|{'|'.join(SHORTFORM_DAYS)})(?:{'|'.join(SHORTFORM_DAY_ENDERS)})?)"
+_month_re = rf"((?:{'|'.join(SHORTFORM_MONTHS)})(?:{'|'.join(SHORTFORM_MONTH_ENDERS)})?)"
+
+#####################
+# Compiled patterns #
+#####################
+
+# "12/04/2523:15", "31/08/202503:15AM"
+_datetime_pattern = re.compile(rf'{_date_re}{re_year}{re_time}{re_am_pm}') # "12/04/2523:15", "31/08/202503:15AM"
+
+# "Tuesday12:30AM", "Today20:00"
+_day_time_pattern = re.compile(rf'{_day_re}{re_time}{re_am_pm}') # "Tuesday12:30AM", "Today20:00
+
+# "17Jul-02:00PM"
+_day_month_time_pattern = re.compile(rf'^(0[0-9]|[12][0-9]|3[01]){_month_re}-?{re_time}{re_am_pm}') # "17Jul-02:00PM"
+
+
+# Event_data patterns (all without spaces)
+TIME_PATTERNS: dict[str, re.Pattern] = {
+    'day_time': _day_time_pattern,
+    'day_month_time': _day_month_time_pattern,
+    'datetime': _datetime_pattern
+}
+
+#################
+# Test fixtures #
+#################
+
+# Unit test cases
+TEST_CASES = [
+        "12/04 22:15",  # 24-hour, no AM/PM, with space
+        "12/04 10:15 PM",  # 12-hour with PM, with spaces
+        "Tuesday 12:30",  # 24-hour weekday, with space
+        "Tuesday 12:30 PM",  # 12-hour weekday, with space
+        "12.04.2025 12:15",  # 24-hour full date, with space
+        "12.04.2025 12:15 pm",  # 12-hour full date, with spaces
+        "Tuesday 02:30 PM",  # 12-hour with space
+        "17 Jul - 02:00",  # 24-hour with month, with spaces
+        "17 Jul - 02:00 PM",  # 12-hour with month, with spaces
+        "Today 14:30",  # 24-hour today, with space
+        "Tomorrow 03:30 PM",  # 12-hour tomorrow, with space
+        # No-space versions
+        "12/0422:15",
+        "Tuesday12:30PM",
+        "17Jul-02:00PM",
+        "Wed1:30am"
+    ]