chronoparse 0.1.0__py3-none-any.whl

chronoparse/__init__.py

@@ -0,0 +1,20 @@
+"""
+chronoparse — Universal datetime parser for all real-world formats.
+
+Supports virtually any date/time format from any country or language.
+"""
+
+from .parser import parse
+from .result import ParsedResult
+from .errors import ParseError, AmbiguousDateError, InvalidDateError
+
+__version__ = "0.1.0"
+__author__ = "Your Name"
+
+__all__ = [
+    "parse",
+    "ParsedResult",
+    "ParseError",
+    "AmbiguousDateError",
+    "InvalidDateError",
+]

chronoparse/cli.py

@@ -0,0 +1,68 @@
+"""
+CLI interface: chronoparse "Oct 5, 2023 2:30 PM"
+"""
+import sys
+import argparse
+from . import parse
+from .errors import ParseError, AmbiguousDateError
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="chronoparse",
+        description="Parse any date/time string"
+    )
+    parser.add_argument(
+        "text",
+        help="Date/time string to parse"
+    )
+    parser.add_argument(
+        "--day-first",
+        action="store_true",
+        default=False,
+        help="Treat first number as day in ambiguous formats"
+    )
+    parser.add_argument(
+        "--iso",
+        action="store_true",
+        default=False,
+        help="Output ISO 8601 format only"
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        default=False,
+        help="Raise error on ambiguous dates"
+    )
+
+    args = parser.parse_args()
+
+    try:
+        result = parse(
+            args.text,
+            day_first=args.day_first,
+            raise_on_ambiguous=args.strict
+        )
+        if args.iso:
+            print(result.isoformat())
+        else:
+            print(f"Parsed:   {result.dt}")
+            print(f"ISO:      {result.isoformat()}")
+            print(f"Format:   {result.format_name}")
+            print(f"Ambiguous:{result.ambiguous}")
+            if result.warnings:
+                for w in result.warnings:
+                    print(f"Warning:  {w}")
+            if result.assumptions:
+                for a in result.assumptions:
+                    print(f"Assumed:  {a}")
+    except ParseError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except AmbiguousDateError as e:
+        print(f"Ambiguous: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

chronoparse/error.py

@@ -0,0 +1,19 @@
+class ParseError(Exception):
+    """Raised when no parser can handle the input."""
+
+    def __init__(self, message: str, original: str = ""):
+        super().__init__(message)
+        self.original = original
+
+
+class AmbiguousDateError(Exception):
+    """Raised when date is ambiguous and strict mode is enabled."""
+
+    def __init__(self, message: str, candidates: list = None):
+        super().__init__(message)
+        self.candidates = candidates or []
+
+
+class InvalidDateError(Exception):
+    """Raised when a parsed date is logically invalid."""
+    pass

chronoparse/errors.py

@@ -0,0 +1,6 @@
+"""Compatibility error module.
+
+This module exists to match expected package structure.
+"""
+
+from .error import *  # noqa: F401,F403

chronoparse/normalizer.py

@@ -0,0 +1,79 @@
+"""
+Input normalization before parsing.
+"""
+import re
+import unicodedata
+
+
+# Filler words that can appear in date strings
+FILLER_WORDS = re.compile(
+    r'\b(at|on|the|of|dated|date)\b',
+    re.IGNORECASE
+)
+
+# Ordinal suffixes
+ORDINAL_SUFFIXES = re.compile(
+    r'(\d+)\s*(st|nd|rd|th)\b',
+    re.IGNORECASE
+)
+
+# Various unicode digit sets mapped to ASCII
+UNICODE_DIGITS = str.maketrans({
+    # Arabic-Indic
+    '٠': '0', '١': '1', '٢': '2', '٣': '3', '٤': '4',
+    '٥': '5', '٦': '6', '٧': '7', '٨': '8', '٩': '9',
+    # Extended Arabic-Indic (Persian)
+    '۰': '0', '۱': '1', '۲': '2', '۳': '3', '۴': '4',
+    '۵': '5', '۶': '6', '۷': '7', '۸': '8', '۹': '9',
+    # Devanagari
+    '०': '0', '१': '1', '२': '2', '३': '3', '४': '4',
+    '५': '5', '६': '6', '७': '7', '८': '8', '९': '9',
+    # Bengali
+    '০': '0', '১': '1', '২': '2', '৩': '3', '৪': '4',
+    '৫': '5', '৬': '6', '৭': '7', '৮': '8', '৯': '9',
+    # Thai
+    '๐': '0', '๑': '1', '๒': '2', '๓': '3', '๔': '4',
+    '๕': '5', '๖': '6', '๗': '7', '๘': '8', '๙': '9',
+    # Myanmar
+    '၀': '0', '၁': '1', '၂': '2', '၃': '3', '၄': '4',
+    '၅': '5', '၆': '6', '၇': '7', '၈': '8', '၉': '9',
+    # Fullwidth
+    '０': '0', '１': '1', '２': '2', '３': '3', '４': '4',
+    '５': '5', '６': '6', '７': '7', '８': '8', '９': '9',
+})
+
+
+def normalize(text: str) -> str:
+    """
+    Normalize a raw datetime string before parsing.
+
+    Steps:
+    1. Strip whitespace
+    2. Normalize unicode digits to ASCII
+    3. Normalize unicode (NFC)
+    4. Remove ordinal suffixes (5th -> 5)
+    5. Remove filler words
+    6. Normalize multiple spaces
+    """
+    if not text:
+        return text
+
+    # strip
+    text = text.strip()
+
+    # normalize unicode digits
+    text = text.translate(UNICODE_DIGITS)
+
+    # NFC normalization
+    text = unicodedata.normalize("NFC", text)
+
+    # remove ordinal suffixes
+    text = ORDINAL_SUFFIXES.sub(r'\1', text)
+
+    # remove filler words
+    text = FILLER_WORDS.sub(' ', text)
+
+    # normalize spaces
+    text = re.sub(r'\s+', ' ', text).strip()
+
+    return text

chronoparse/parser.py

@@ -0,0 +1,118 @@
+"""
+Main entry point for chronoparse.
+"""
+from .normalizer import normalize
+from .result import ParsedResult
+from .errors import ParseError, AmbiguousDateError
+
+from .parsers import (
+    timestamp,
+    iso8601,
+    rfc2822,
+    textual,
+    numeric,
+    asian,
+    special,
+    time_only,
+    locale_formats,
+)
+
+
+# Parser pipeline: order determines priority
+# Most specific / unambiguous parsers come first
+PARSERS = [
+    timestamp,        # unix timestamps (pure numeric, very specific)
+    iso8601,          # ISO 8601 / RFC 3339
+    rfc2822,          # RFC 2822 email headers
+    asian,            # Japanese/Chinese/Korean with kanji markers
+    locale_formats,   # German "5. Oktober", Japanese era
+    textual,          # English and multilingual month names
+    special,          # Quarter, year-month, pure numeric datetime
+    numeric,          # Numeric date formats (MM/DD/YYYY etc)
+    time_only,        # Time-only formats
+]
+
+
+def parse(
+    text: str,
+    *,
+    day_first: bool = False,
+    raise_on_ambiguous: bool = False,
+) -> ParsedResult:
+    """
+    Parse any date/time string into a ParsedResult.
+
+    Parameters
+    ----------
+    text : str
+        The date/time string to parse. Can be in virtually any
+        format from any country or language.
+    day_first : bool, optional
+        For ambiguous formats like 05/10/2023, treat the first
+        number as the day (DD/MM/YYYY). Default is False (MM/DD/YYYY).
+    raise_on_ambiguous : bool, optional
+        If True, raise AmbiguousDateError for ambiguous dates
+        instead of returning a best-effort result.
+
+    Returns
+    -------
+    ParsedResult
+        Contains the parsed datetime, format name, and metadata.
+
+    Raises
+    ------
+    TypeError
+        If input is not a string.
+    ParseError
+        If no parser can handle the input.
+    AmbiguousDateError
+        If raise_on_ambiguous=True and the result is ambiguous.
+
+    Examples
+    --------
+    >>> from chronoparse import parse
+    >>> parse("2023-10-05T14:30:00Z")
+    ParsedResult(dt='2023-10-05T14:30:00+00:00', format='iso8601_datetime', ambiguous=False)
+
+    >>> parse("October 5, 2023 2:30 PM")
+    ParsedResult(dt='2023-10-05T14:30:00', format='textual_mdy', ambiguous=False)
+
+    >>> parse("05/10/2023", day_first=True)
+    ParsedResult(dt='2023-10-05T00:00:00', format='numeric_dmy_mdy', ambiguous=True)
+
+    >>> parse("1696516200")
+    ParsedResult(dt='2023-10-05T18:30:00+00:00', format='unix_timestamp_seconds', ambiguous=False)
+    """
+    if not isinstance(text, str):
+        raise TypeError(
+            f"parse() expects a str, got {type(text).__name__!r}"
+        )
+
+    if not text.strip():
+        raise ParseError("Input string is empty.", original=text)
+
+    normalized = normalize(text)
+
+    for parser_module in PARSERS:
+        try:
+            result = parser_module.parse(
+                normalized,
+                day_first=day_first,
+            )
+            if result is not None:
+                if raise_on_ambiguous and result.ambiguous:
+                    raise AmbiguousDateError(
+                        f"Ambiguous date: '{text}'. "
+                        f"Use day_first=True or day_first=False to resolve.",
+                        candidates=[]
+                    )
+                return result
+        except (ValueError, OverflowError, OSError):
+            continue
+        except (ParseError, AmbiguousDateError):
+            raise
+
+    raise ParseError(
+        f"Unable to parse datetime string: '{text}'",
+        original=text
+    )

chronoparse/parsers/__init__.py

@@ -0,0 +1,23 @@
+from . import (
+    timestamp,
+    iso8601,
+    rfc2822,
+    textual,
+    numeric,
+    asian,
+    special,
+    time_only,
+    locale_formats,
+)
+
+__all__ = [
+    "timestamp",
+    "iso8601",
+    "rfc2822",
+    "textual",
+    "numeric",
+    "asian",
+    "special",
+    "time_only",
+    "locale_formats",
+]

chronoparse/parsers/asian.py

@@ -0,0 +1,100 @@
+"""
+Asian date/time formats.
+
+Japanese:  2023年10月5日  /  2023年10月5日 14時30分00秒
+Chinese:   2023年10月5日  /  2023年10月5日 14时30分
+Korean:    2023년 10월 5일  /  2023년 10월 5일 14시 30분
+Thai:      พ.ศ. 2566 (Buddhist calendar)
+"""
+import re
+from datetime import datetime
+from ..result import ParsedResult
+
+
+# ── Japanese / Chinese ───────────────────────────────────────────────────────
+JA_ZH_DATE = re.compile(
+    r'(\d{4})[年]'
+    r'\s*(\d{1,2})[月]'
+    r'\s*(\d{1,2})[日号]?'
+    r'(?:\s*(\d{1,2})[时時時]'
+    r'\s*(\d{1,2})[分]'
+    r'(?:\s*(\d{1,2})[秒])?)?'
+)
+
+# ── Korean ────────────────────────────────────────────────────────────────────
+KO_DATE = re.compile(
+    r'(\d{4})[년]'
+    r'\s*(\d{1,2})[월]'
+    r'\s*(\d{1,2})[일]'
+    r'(?:\s*(\d{1,2})[시]'
+    r'\s*(\d{1,2})[분]'
+    r'(?:\s*(\d{1,2})[초])?)?'
+)
+
+# ── Thai Buddhist year ────────────────────────────────────────────────────────
+# พ.ศ. 2566 เดือน 10 วันที่ 5
+THAI_DATE = re.compile(
+    r'(?:พ\.ศ\.\s*)?(\d{4})'
+    r'\s*(?:เดือน)?\s*(\d{1,2})'
+    r'\s*(?:วันที่)?\s*(\d{1,2})'
+)
+
+
+def _buddhist_to_gregorian(year: int) -> int:
+    """Convert Thai Buddhist year to Gregorian."""
+    return year - 543
+
+
+def parse(text: str, **kwargs) -> ParsedResult | None:
+    text = text.strip()
+
+    # ── Japanese / Chinese ───────────────────────────────────────────────────
+    m = JA_ZH_DATE.search(text)
+    if m:
+        try:
+            year = int(m.group(1))
+            month = int(m.group(2))
+            day = int(m.group(3))
+            hour = int(m.group(4)) if m.group(4) else 0
+            minute = int(m.group(5)) if m.group(5) else 0
+            second = int(m.group(6)) if m.group(6) else 0
+            dt = datetime(year, month, day, hour, minute, second)
+            return ParsedResult(dt=dt, original=text, format_name="japanese_chinese")
+        except (ValueError, TypeError):
+            pass
+
+    # ── Korean ───────────────────────────────────────────────────────────────
+    m = KO_DATE.search(text)
+    if m:
+        try:
+            year = int(m.group(1))
+            month = int(m.group(2))
+            day = int(m.group(3))
+            hour = int(m.group(4)) if m.group(4) else 0
+            minute = int(m.group(5)) if m.group(5) else 0
+            second = int(m.group(6)) if m.group(6) else 0
+            dt = datetime(year, month, day, hour, minute, second)
+            return ParsedResult(dt=dt, original=text, format_name="korean")
+        except (ValueError, TypeError):
+            pass
+
+    # ── Thai Buddhist ─────────────────────────────────────────────────────────
+    if 'พ.ศ.' in text or 'เดือน' in text or 'วันที่' in text:
+        m = THAI_DATE.search(text)
+        if m:
+            try:
+                buddhist_year = int(m.group(1))
+                year = _buddhist_to_gregorian(buddhist_year)
+                month = int(m.group(2))
+                day = int(m.group(3))
+                dt = datetime(year, month, day)
+                return ParsedResult(
+                    dt=dt,
+                    original=text,
+                    format_name="thai_buddhist",
+                    assumptions=[f"Converted Buddhist year {buddhist_year} to Gregorian {year}"]
+                )
+            except (ValueError, TypeError):
+                pass
+
+    return None

chronoparse/parsers/iso8601.py

@@ -0,0 +1,175 @@
+"""
+ISO 8601 and RFC 3339 parser.
+Covers all standard variants including compact, week dates,
+fractional seconds, and timezone offsets.
+"""
+import re
+from datetime import datetime, timezone, date
+from ..result import ParsedResult
+from ..utils.timezone_map import resolve_timezone
+
+
+# ── Timezone pattern ─────────────────────────────────────────────────────────
+TZ_PAT = r'(Z|UTC|GMT|[+-]\d{2}:?\d{2}|[+-]\d{2})?'
+
+# ── All ISO patterns ──────────────────────────────────────────────────────────
+ISO_PATTERNS = [
+
+    # ── Full datetime with fractional seconds ────────────────────────────────
+    # 2023-10-05T14:30:00.123456Z
+    (
+        re.compile(
+            r'(\d{4})-(\d{2})-(\d{2})'
+            r'[T ]'
+            r'(\d{2}):(\d{2}):(\d{2})\.(\d+)'
+            + TZ_PAT, re.IGNORECASE
+        ),
+        "iso8601_datetime_fractional"
+    ),
+
+    # ── Full datetime with timezone ──────────────────────────────────────────
+    # 2023-10-05T14:30:00Z
+    (
+        re.compile(
+            r'(\d{4})-(\d{2})-(\d{2})'
+            r'[T ]'
+            r'(\d{2}):(\d{2}):(\d{2})'
+            + TZ_PAT, re.IGNORECASE
+        ),
+        "iso8601_datetime"
+    ),
+
+    # ── Datetime without seconds ─────────────────────────────────────────────
+    # 2023-10-05T14:30Z
+    (
+        re.compile(
+            r'(\d{4})-(\d{2})-(\d{2})'
+            r'[T ]'
+            r'(\d{2}):(\d{2})'
+            + TZ_PAT, re.IGNORECASE
+        ),
+        "iso8601_datetime_no_seconds"
+    ),
+
+    # ── Date only ────────────────────────────────────────────────────────────
+    # 2023-10-05
+    (
+        re.compile(r'(\d{4})-(\d{2})-(\d{2})$'),
+        "iso8601_date"
+    ),
+
+    # ── Compact datetime ─────────────────────────────────────────────────────
+    # 20231005T143000Z
+    (
+        re.compile(
+            r'(\d{4})(\d{2})(\d{2})'
+            r'T'
+            r'(\d{2})(\d{2})(\d{2})'
+            + TZ_PAT, re.IGNORECASE
+        ),
+        "iso8601_compact_datetime"
+    ),
+
+    # ── Compact date ─────────────────────────────────────────────────────────
+    # 20231005
+    (
+        re.compile(r'^(\d{4})(\d{2})(\d{2})$'),
+        "iso8601_compact_date"
+    ),
+
+    # ── ISO Week date ────────────────────────────────────────────────────────
+    # 2023-W40-4
+    (
+        re.compile(r'(\d{4})-W(\d{2})(?:-([1-7]))?'),
+        "iso8601_week"
+    ),
+
+    # ── Ordinal date ─────────────────────────────────────────────────────────
+    # 2023-278
+    (
+        re.compile(r'(\d{4})-(\d{3})$'),
+        "iso8601_ordinal"
+    ),
+]
+
+
+def _resolve_tz(tz_str: str | None) -> timezone | None:
+    if not tz_str:
+        return None
+    return resolve_timezone(tz_str)
+
+
+def parse(text: str, **kwargs) -> ParsedResult | None:
+    text = text.strip()
+
+    for pattern, name in ISO_PATTERNS:
+        m = pattern.fullmatch(text)
+        if not m:
+            continue
+
+        g = m.groups()
+
+        try:
+            # ISO week date
+            if name == "iso8601_week":
+                year = int(g[0])
+                week = int(g[1])
+                day_of_week = int(g[2]) if g[2] else 1
+                dt = datetime.fromisocalendar(year, week, day_of_week)
+                return ParsedResult(dt=dt, original=text, format_name=name)
+
+            # Ordinal date
+            if name == "iso8601_ordinal":
+                year = int(g[0])
+                ordinal = int(g[1])
+                dt = datetime(year, 1, 1) + __import__('datetime').timedelta(days=ordinal - 1)
+                return ParsedResult(dt=dt, original=text, format_name=name)
+
+            year, month, day = int(g[0]), int(g[1]), int(g[2])
+
+            # date only
+            if name in ("iso8601_date", "iso8601_compact_date"):
+                dt = datetime(year, month, day)
+                return ParsedResult(dt=dt, original=text, format_name=name)
+
+            hour = int(g[3])
+            minute = int(g[4])
+
+            # no seconds
+            if name == "iso8601_datetime_no_seconds":
+                tz = _resolve_tz(g[5])
+                dt = datetime(year, month, day, hour, minute, tzinfo=tz)
+                return ParsedResult(
+                    dt=dt, original=text,
+                    format_name=name,
+                    timezone_str=g[5]
+                )
+
+            second = int(g[5])
+
+            # fractional seconds
+            if name == "iso8601_datetime_fractional":
+                frac = g[6]
+                microsecond = int(frac.ljust(6, "0")[:6])
+                tz = _resolve_tz(g[7])
+                dt = datetime(year, month, day, hour, minute,
+                              second, microsecond, tzinfo=tz)
+                return ParsedResult(
+                    dt=dt, original=text,
+                    format_name=name,
+                    timezone_str=g[7]
+                )
+
+            # standard datetime
+            tz = _resolve_tz(g[6])
+            dt = datetime(year, month, day, hour, minute, second, tzinfo=tz)
+            return ParsedResult(
+                dt=dt, original=text,
+                format_name=name,
+                timezone_str=g[6]
+            )
+
+        except (ValueError, TypeError):
+            continue
+
+    return None