convi-lab 0.1.0__py3-none-any.whl

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/conversion_kernel/__init__.py

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

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"
+    ]

convi_lab/conversion_kernel/errors.py

@@ -0,0 +1,255 @@
+"""
+errors.py — Exception hierarchy for convi-lab.
+
+All exceptions inherit from :class:`LabError` so library consumers can
+write a single broad ``except LabError`` or catch specific subclasses
+for fine-grained handling.
+
+Hierarchy
+---------
+::
+
+    LabError
+    ├── ParserError
+    │   ├── PatternMatchError      no TIME_PATTERNS entry matched the raw input
+    │   ├── DayResolutionError     weekday or relative-day string is unresolvable
+    │   ├── MonthResolutionError   month name string is unresolvable
+    │   └── DateComponentError     numeric date fragment (day/month/year) is malformed
+    └── ConversionError
+        ├── ClockFormatError       HH:MM[AM|PM] string failed to parse
+        ├── FuzzyMatchError        rapidfuzz returned no result or raised internally
+        └── InvalidInputError      bad type or empty string passed to convert_date_time
+
+Design notes
+------------
+* Every leaf class accepts the minimum arguments needed to produce a
+  self-describing message so callers never have to format strings
+  themselves.
+* ``errors.py`` imports nothing from the rest of the package — it sits
+  at the base of the dependency graph and is safe to import from anywhere.
+* ``convert_date_time`` is the only public function that swallows
+  ``LabError``; all other callables let errors propagate so the caller
+  can decide how to handle them.
+"""
+
+########
+# Root #
+########
+
+class LabError(Exception):
+    """
+    Base class for all convi-lab exceptions.
+
+    Catch this to handle any error the library can raise::
+
+        try:
+            result = convert_date_time(raw)
+        except LabError as exc:
+            print(f' convi-lab error: {exc}')
+    """
+
+##################
+# Parser errors  #
+##################
+
+class ParserError(LabError):
+    """
+    Base class for all parse-time failures.
+
+    Raised (or subclassed) whenever a raw string cannot be turned into a
+    ``datetime`` — either because no regex pattern matched or because a
+    matched component (day, month, date fragment) could not be resolved
+    to a concrete value.
+    """
+
+class PatternMatchError(ParserError):
+    """
+    Raised when no entry in ``TIME_PATTERNS`` matches the input string.
+    This fires in `process_patterns()` after all patterns have been tried
+     and none produced a match.
+
+    Example:
+        raise PatternMatchError("badstring", ["day_time", "day_month_time", "datetime"])
+        # PatternMatchError: 'badstring' did not match any known pattern.
+        # Available patterns: day_time, day_month_time, datetime
+    Args:
+        input_str: The cleaned (space-stripped) string that was tested.
+        available_patterns: Sequence of pattern names that were tried.
+    """
+
+    def __init__(self, input_str: str, available_patterns: list[str]) -> None:
+        patterns = ", ".join(available_patterns)
+
+        super().__init__(
+            f"'{input_str}' did not match any known pattern. "
+            f"Available patterns: {patterns}"
+        )
+
+class DayResolutionError(ParserError):
+    """
+    Raised when a day string cannot be resolved to a weekday or relative day.
+
+    Fired inside `parse_day_time()` when fuzzy matching returns a value that
+    is neither in ``WEEKDAY_MAP`` nor in ``RELATIVE_DAYS``.
+
+    Example:
+        raise DayResolutionError("Xyz")
+        # DayResolutionError: 'Xyz' could not be resolved to a weekday or
+        # relative day. Valid values: Today, Tomorrow, Monday … Sunday
+    Args:
+        day_str: The raw day string that could not be resolved
+                 (e.g. ``"Mnday"``, ``"Xyz"``).
+    """
+
+    _VALID = (
+        "Today", "Tomorrow",
+        "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday",
+    )
+
+    def __init__(self, day_str: str) -> None:
+        valid = ", ".join(self._VALID)
+
+        super().__init__(
+            f"'{day_str}' could not be resolved to a weekday or relative day. "
+            f"Valid values: {valid}"
+        )
+
+class MonthResolutionError(ParserError):
+    """
+    Raised when a month string cannot be resolved to a calendar month.
+
+    Fired inside `parse_day_month_time()` when fuzzy matching returns
+    an empty result for the month component.
+
+    Example:
+        raise MonthResolutionError("Jly")
+        # MonthResolutionError: 'Jly' could not be resolved to a calendar month.
+        # Valid values: January, February, … December
+    Args:
+        month_str: The raw month string that could not be resolved
+                   (e.g. ``"Jly"``, ``"Xyz"``).
+    """
+
+    _VALID = (
+        "January", "February", "March", "April", "May", "June",
+        "July", "August", "September", "October", "November", "December",
+    )
+
+    def __init__(self, month_str: str) -> None:
+        valid = ", ".join(self._VALID)
+
+        super().__init__(
+            f"'{month_str}' could not be resolved to a calendar month. "
+            f"Valid values: {valid}"
+        )
+
+class DateComponentError(ParserError):
+    """
+    Raised when a numeric date fragment is structurally malformed.
+
+    Covers year fragments (``"/99"``, ``".20255"``), day-of-month values
+    outside 1–31, and month numbers outside 1–12 that pass regex
+    screening but fail ``datetime.strptime``.
+
+    Example:
+        raise DateComponentError("/999", "year fragment must be 2 or 4 digits")
+        # DateComponentError: date fragment '/999' is malformed:
+        #   year fragment must be 2 or 4 digits
+    Args:
+        fragment: The raw string fragment that could not be parsed
+                  (e.g. ``"/999"``, ``"32/13"``).
+        reason:   Human-readable explanation of what went wrong.
+    """
+
+    def __init__(self, fragment: str, reason: str) -> None:
+        super().__init__(
+            f"date fragment '{fragment}' is malformed: {reason}"
+        )
+
+
+######################
+# Conversion errors  #
+######################
+
+class ConversionError(LabError):
+    """
+    Base class for all conversion-time failures.
+
+    Raised (or subclassed) whenever a structurally valid component
+    (time string, fuzzy name query, or entry-point input) cannot be
+    converted to its target type.
+    """
+
+class ClockFormatError(ConversionError):
+    """
+    Raised when an HH:MM[AM|PM] string cannot be parsed.
+
+    Fired by `convert_to_24_format()` when `datetime.strptime()`
+    rejects the assembled time string.
+
+     Example:
+        raise ClockFormatError("25:00", None)
+        # ClockFormatError: cannot parse '25:00' as a 24-hour time (HH:MM)
+
+        raise ClockFormatError("09:99", "PM")
+        # ClockFormatError: cannot parse '09:99PM' as a 12-hour time (HH:MM AM/PM)
+    Args:
+        time:   The raw ``HH:MM`` fragment (e.g. ``"25:00"``, ``"9:99"``).
+        am_pm:  The AM/PM suffix if 12-hour mode was requested, else ``None``.
+    """
+
+    def __init__(self, time: str, am_pm: str | None) -> None:
+        if am_pm:
+            raw  = f"{time}{am_pm.upper()}"
+            fmt  = "12-hour time (HH:MM AM/PM)"
+        else:
+            raw  = time
+            fmt  = "24-hour time (HH:MM)"
+
+        super().__init__(f"cannot parse '{raw}' as a {fmt}")
+
+class FuzzyMatchError(ConversionError):
+    """
+    Raised when rapidfuzz finds no match for the given query.
+
+    Fired by `convert_name()` when ``process.extractOne``
+    returns ``None`` or raises internally.
+
+    Example:
+        raise FuzzyMatchError("xyz", 12)
+        # FuzzyMatchError: fuzzy match found no result for 'xyz'
+        #   in a reference list of 12 items
+    Args:
+        name:      The query string that could not be matched.
+        ref_count: Number of items in the reference list (aids debugging).
+    """
+
+    def __init__(self, name: str, ref_count: int) -> None:
+        super().__init__(
+            f"fuzzy match found no result for '{name}' "
+            f"in a reference list of {ref_count} item{'s' if ref_count != 1 else ''}"
+        )
+
+class InvalidInputError(ConversionError):
+    """
+    Raised when the value passed to ``convert_date_time()`` is not a
+    non-empty string.
+
+    Example:
+        raise InvalidInputError(None)
+        # InvalidInputError: expected a non-empty str, got NoneType: None
+
+        raise InvalidInputError("")
+        # InvalidInputError: expected a non-empty str, got an empty string
+    Args:
+        value: The invalid value that was provided.
+    """
+
+    def __init__(self, value: object) -> None:
+        if value == "":
+            detail = "got an empty string"
+
+        else:
+            detail = f"got {type(value).__name__}: {value!r}"
+
+        super().__init__(f"expected a non-empty str, {detail}")

convi_lab/conversion_kernel/pattern_parsers.py

@@ -0,0 +1,53 @@
+from logger_lab import lab
+from datetime import datetime
+from typing import Optional, Callable
+
+from convi_lab.conversion_kernel.constants import TIME_PATTERNS
+from convi_lab.parsers import parse_day_month_time, parse_day_time, parse_date_time
+
+logger = (
+    lab()
+    .with_profile("INVESTIGATOR")
+    .with_level("ERROR")
+    .build(__name__)
+)
+
+# MAPS PATTERNS TO FUNCTIONS
+_PATTERN_HANDLERS: dict[str, Callable] = {
+    'day_time': parse_day_time,
+    'day_month_time': parse_day_month_time,
+    'datetime': parse_date_time,
+}
+
+
+# Match and parse pattern
+def process_patterns(event_date: str) -> Optional[datetime]:
+    """
+    Try every pattern in ``TIME_PATTERNS`` against *event_date* in order,
+    returning the first successful ``datetime`` parse.
+
+    Note:
+        All spaces must be removed from *event_date* before calling this
+        function — use `remove_spaces()`.
+
+    Args:
+        event_date: Date/time string with all spaces already stripped.
+    Returns:
+        Parsed ``datetime`` on the first pattern match, or ``None`` if
+        no pattern matches.
+    """
+
+    # Check each pattern till a match is found
+    for pattern_name, pattern in TIME_PATTERNS.items():
+
+        if match := pattern.match(event_date):
+
+            handler = _PATTERN_HANDLERS[pattern_name]
+            _date_time = handler(match)
+
+            logger.debug(f"Matched pattern '{pattern_name}' for input '{event_date}'")
+
+            return _date_time
+
+    # Fallback
+    return None

convi_lab/conversion_kernel/utils.py

@@ -0,0 +1,81 @@
+import re
+from datetime import datetime
+
+
+from convi_lab.conversion_kernel.constants import TIME_PATTERNS
+
+
+# Returns a match object for unit tests
+def match_pattern(pattern_name: str, case: str) -> re.Match:
+    """
+    Return a match object for *case* against the named pattern.
+    Used in unit tests and standalone ``__main__`` blocks.
+
+    Args:
+        pattern_name: Key into ``TIME_PATTERNS`` (e.g. ``"datetime"``).
+        case: Raw date/time string (spaces already removed).
+    Returns:
+    ``re.Match`` if the pattern matches, else ``None``.
+    Raises:
+        KeyError:
+            If *pattern_name* is not in ``TIME_PATTERNS``.
+    """
+
+    return TIME_PATTERNS[pattern_name].match(case)
+
+
+# Test the output of a regex
+def _test_pattern(pattern: re.Pattern, case: str) -> tuple[str, ...]:
+    """
+    Assert that *case* matches *pattern* and return the captured groups.
+
+    Args:
+        pattern: A compiled regex pattern.
+        case: Input string to test.
+    Returns:
+        Tuple of captured groups.
+    Raises:
+        ValueError:
+            If *case* does not match.
+    """
+
+    if match := pattern.match(case):
+        return match.groups()
+
+    raise ValueError(f"{case} is not a valid pattern\n Valid pattern: {pattern}")
+
+
+# Remove all spaces from string
+def remove_spaces(value: str) -> str:
+    """Strip all whitespace characters from *value*."""
+
+    return value.replace(' ', '')
+
+
+# Used in a parser to build the datetime object
+def parser_handler(date_object, time_str, am_pm):
+    """
+    Builds datetime object after *date_object* in a parser.
+
+    Args:
+        date_object: ``dd.mm.yyyy``
+        time_str: ``HH:MM`` string
+        am_pm: ``"AM"`` / ``"PM"`` / ``None``
+    Returns:
+        Parsed and potentially year-corrected ``datetime``.
+    """
+
+    # Good old lazy loading to avoid circling
+    from convi_lab import convert_to_24_format
+
+    time_object = convert_to_24_format(time=time_str, am_pm=am_pm)
+
+    # Combine date and time
+    _datetime = datetime.combine(date_object.date(), time_object.time())
+
+    # Handle year boundary (if parsed date is in the past, assume next year)
+    # Compare only the date part, not the time
+    if date_object.date() < datetime.now().date():
+        _datetime = _datetime.replace(year=datetime.now().year + 1)
+
+    return _datetime

convi_lab/conversions/__init__.py

@@ -0,0 +1,11 @@
+""" DATA CONVERSION HANDLERS """
+
+from .convert_clock_format import convert_to_24_format
+from .convert_name import convert_name
+from .convert_datetime import convert_date_time
+
+__all__ = [
+    "convert_to_24_format",
+    "convert_name",
+    "convert_date_time"
+]

convi_lab/conversions/convert_clock_format.py

@@ -0,0 +1,70 @@
+"""
+convert_clock_format.py — Normalise any HH:MM[AM|PM] string to a 24-hour datetime.
+"""
+
+from logger_lab import lab
+from typing import Optional
+from datetime import datetime
+
+from convi_lab.conversion_kernel.errors import ClockFormatError
+
+logger = (
+    lab()
+    .with_profile("INVESTIGATOR")
+    .with_level("ERROR")
+    .build(__name__)
+)
+
+# RUN CONVERT FORMAT
+
+# Convert 12-hour to 24-hour format
+def convert_to_24_format(time: str, am_pm: Optional[str] = None) -> datetime:
+    """
+    Parse a time string into a ``datetime`` object, normalising to 24-hour time.
+
+    When *am_pm* is provided the input is treated as 12-hour clock; otherwise
+    it is assumed to already be in 24-hour format.
+
+    Examples:
+        convert_to_24_format("14:30")          # → datetime(... 14, 30)
+        convert_to_24_format("02:30", "PM")    # → datetime(... 14, 30)
+        convert_to_24_format("12:00", "AM")    # → datetime(... 0, 0)
+    Args:
+        time: Time in ``HH:MM`` format, no spaces (e.g. ``"02:30"``).
+        am_pm: Optional AM/PM suffix — case-insensitive
+            (``"AM"``, ``"pm"``, ``"Pm"`` …).  Pass ``None`` for 24-hour input.
+    Returns:
+        ``datetime`` object carrying only the parsed time component.
+    Raises:
+        ClockFormatError:
+            If the string cannot be parsed under the chosen format.
+    """
+
+    if am_pm:
+        # 12-hour format conversion
+        am_pm = am_pm.upper()
+        try:
+            return datetime.strptime(f"{time}{am_pm}", "%I:%M%p")
+
+        except ValueError:
+            logger.error(f"Failed to parse 12-hour time: {time}{am_pm}")
+            raise ClockFormatError(time, am_pm)
+
+    else:
+        # 24-hour format
+        try:
+            return datetime.strptime(time, "%H:%M")
+
+        except ValueError:
+            logger.error(f"Failed to parse 24-hour time: {time}")
+            raise ClockFormatError(time, None)
+
+
+# Example usage and test case
+def test_case():
+    logger.debug(convert_to_24_format('12:36', 'AM'))
+
+
+if __name__ == '__main__':
+    # TEST
+    test_case()