datemonkey 0.1.0__py3-none-any.whl

datemonkey/formats.py

@@ -0,0 +1,133 @@
+"""Known date format patterns and detection logic."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from .models import DateFormat
+
+# ── Well-known formats, ordered from most specific to least ──────────────
+
+ISO_8601 = DateFormat("%Y-%m-%d", "ISO 8601", "2024-03-15")
+ISO_8601_T = DateFormat("%Y-%m-%dT%H:%M:%S", "ISO 8601 datetime", "2024-03-15T14:30:00")
+ISO_8601_TZ = DateFormat("%Y-%m-%dT%H:%M:%S%z", "ISO 8601 with timezone", "2024-03-15T14:30:00+00:00")
+
+US_SLASH = DateFormat("%m/%d/%Y", "US date (MM/DD/YYYY)", "03/15/2024")
+US_SLASH_SHORT = DateFormat("%m/%d/%y", "US date short year (MM/DD/YY)", "03/15/24")
+US_DASH = DateFormat("%m-%d-%Y", "US date dash (MM-DD-YYYY)", "03-15-2024")
+
+EU_SLASH = DateFormat("%d/%m/%Y", "European date (DD/MM/YYYY)", "15/03/2024")
+EU_SLASH_SHORT = DateFormat("%d/%m/%y", "European date short year (DD/MM/YY)", "15/03/24")
+EU_DASH = DateFormat("%d-%m-%Y", "European date dash (DD-MM-YYYY)", "15-03-2024")
+EU_DOT = DateFormat("%d.%m.%Y", "European date dot (DD.MM.YYYY)", "15.03.2024")
+EU_DOT_SHORT = DateFormat("%d.%m.%y", "European date dot short (DD.MM.YY)", "15.03.24")
+
+YYYYMMDD = DateFormat("%Y%m%d", "Compact (YYYYMMDD)", "20240315")
+
+YYYY_MM_DD_SLASH = DateFormat("%Y/%m/%d", "Year-first slash (YYYY/MM/DD)", "2024/03/15")
+
+MONTH_NAME_DMY = DateFormat("%d %B %Y", "Day Month Year (15 March 2024)", "15 March 2024")
+MONTH_NAME_MDY = DateFormat("%B %d, %Y", "Month Day, Year (March 15, 2024)", "March 15, 2024")
+MONTH_ABBR_DMY = DateFormat("%d %b %Y", "Day Mon Year (15 Mar 2024)", "15 Mar 2024")
+MONTH_ABBR_MDY = DateFormat("%b %d, %Y", "Mon Day, Year (Mar 15, 2024)", "Mar 15, 2024")
+MONTH_ABBR_MDY_NO_COMMA = DateFormat("%b %d %Y", "Mon Day Year (Mar 15 2024)", "Mar 15 2024")
+MONTH_NAME_MDY_NO_COMMA = DateFormat("%B %d %Y", "Month Day Year (March 15 2024)", "March 15 2024")
+
+# With time components
+US_SLASH_TIME = DateFormat("%m/%d/%Y %H:%M:%S", "US datetime", "03/15/2024 14:30:00")
+US_SLASH_TIME_12 = DateFormat("%m/%d/%Y %I:%M:%S %p", "US datetime 12h", "03/15/2024 02:30:00 PM")
+EU_SLASH_TIME = DateFormat("%d/%m/%Y %H:%M:%S", "European datetime", "15/03/2024 14:30:00")
+ISO_SPACE = DateFormat("%Y-%m-%d %H:%M:%S", "ISO datetime (space)", "2024-03-15 14:30:00")
+
+# ── Format groups ────────────────────────────────────────────────────────
+
+# Formats where day and month positions are unambiguous
+UNAMBIGUOUS_FORMATS: list[DateFormat] = [
+    ISO_8601_TZ,
+    ISO_8601_T,
+    ISO_8601,
+    ISO_SPACE,
+    YYYY_MM_DD_SLASH,
+    YYYYMMDD,
+    MONTH_NAME_MDY,
+    MONTH_NAME_DMY,
+    MONTH_ABBR_MDY,
+    MONTH_ABBR_DMY,
+    MONTH_ABBR_MDY_NO_COMMA,
+    MONTH_NAME_MDY_NO_COMMA,
+]
+
+# US formats (MM/DD)
+US_FORMATS: list[DateFormat] = [
+    US_SLASH,
+    US_SLASH_SHORT,
+    US_DASH,
+    US_SLASH_TIME,
+    US_SLASH_TIME_12,
+]
+
+# European formats (DD/MM)
+EU_FORMATS: list[DateFormat] = [
+    EU_SLASH,
+    EU_SLASH_SHORT,
+    EU_DASH,
+    EU_DOT,
+    EU_DOT_SHORT,
+    EU_SLASH_TIME,
+]
+
+# All formats for detection, in priority order
+ALL_FORMATS: list[DateFormat] = UNAMBIGUOUS_FORMATS + US_FORMATS + EU_FORMATS
+
+# ── Ambiguous pairs: formats that differ only in day/month position ──────
+
+AMBIGUOUS_PAIRS: list[tuple[DateFormat, DateFormat]] = [
+    (US_SLASH, EU_SLASH),
+    (US_SLASH_SHORT, EU_SLASH_SHORT),
+    (US_DASH, EU_DASH),
+    (US_SLASH_TIME, EU_SLASH_TIME),
+]
+
+# ── Regex for quick pre-screening ────────────────────────────────────────
+
+# Matches potential Excel serial date numbers (integers 1-2958465 or floats)
+EXCEL_SERIAL_RE = re.compile(r"^\d{1,7}(\.\d+)?$")
+
+# Quick check: does this look like a date-ish string at all?
+DATE_LIKE_RE = re.compile(
+    r"(?:"
+    r"\d{1,4}[\-/\.]\d{1,2}[\-/\.]\d{1,4}"  # numeric with separators
+    r"|\d{8}"  # YYYYMMDD
+    r"|\d{1,2}\s+\w+\s+\d{2,4}"  # 15 March 2024
+    r"|\w+\s+\d{1,2},?\s+\d{2,4}"  # March 15, 2024
+    r"|\d{4}-\d{2}-\d{2}T"  # ISO with T
+    r")",
+    re.IGNORECASE,
+)
+
+
+def is_date_like(value: str) -> bool:
+    """Quick check whether a string looks like it could be a date."""
+    return bool(DATE_LIKE_RE.search(value.strip()))
+
+
+def could_be_excel_serial(value: str) -> bool:
+    """Check whether a string looks like an Excel serial date number."""
+    s = value.strip()
+    if not EXCEL_SERIAL_RE.match(s):
+        return False
+    num = float(s)
+    # Excel serial dates: 1 = 1900-01-01, reasonable range up to ~2958465 (9999-12-31)
+    # But practically, most dates are between 1 (1900) and ~55000 (2050+)
+    return 1 <= num <= 2958465
+
+
+def get_ambiguous_partner(fmt: DateFormat) -> Optional[DateFormat]:
+    """If a format has a DD/MM vs MM/DD ambiguous partner, return it."""
+    for a, b in AMBIGUOUS_PAIRS:
+        if fmt == a:
+            return b
+        if fmt == b:
+            return a
+    return None

datemonkey/models.py

@@ -0,0 +1,196 @@
+"""Result models for datemonkey."""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class AmbiguityType(Enum):
+    """Types of date ambiguity."""
+
+    NONE = "none"
+    DAY_MONTH_SWAP = "day_month_swap"  # DD/MM vs MM/DD
+    TWO_DIGIT_YEAR = "two_digit_year"  # 03 -> 2003 or 1903?
+    MIXED_FORMATS = "mixed_formats"  # Multiple formats in batch
+
+
+class Confidence(Enum):
+    """Confidence levels for parsed dates."""
+
+    HIGH = "high"  # Unambiguous parse
+    MEDIUM = "medium"  # Likely correct but some ambiguity
+    LOW = "low"  # Ambiguous, could be wrong
+    FAILED = "failed"  # Could not parse
+
+
+@dataclass(frozen=True)
+class DateFormat:
+    """A detected or specified date format.
+
+    Attributes:
+        pattern: strftime-compatible format string (e.g. "%Y-%m-%d").
+        label: Human-readable name (e.g. "ISO 8601", "US date", "European date").
+        example: Example value matching this format.
+    """
+
+    pattern: str
+    label: str
+    example: str = ""
+
+    def __str__(self) -> str:
+        return self.pattern
+
+
+@dataclass
+class DateResult:
+    """Result of parsing a single date value.
+
+    Returned as part of a BatchResult. Downstream consumers should check
+    ``confidence`` and ``warnings`` before using ``parsed``.
+
+    Attributes:
+        original: The raw input value.
+        parsed: The parsed datetime, or None if parsing failed.
+        format_used: The DateFormat applied.
+        confidence: How confident we are in the parse.
+        warnings: Any issues detected (ambiguity, coercion, etc.).
+        row_index: Optional position in the source batch.
+    """
+
+    original: Any
+    parsed: Optional[datetime.datetime] = None
+    format_used: Optional[DateFormat] = None
+    confidence: Confidence = Confidence.FAILED
+    warnings: list[str] = field(default_factory=list)
+    row_index: Optional[int] = None
+
+    @property
+    def ok(self) -> bool:
+        """True if the value was parsed successfully."""
+        return self.parsed is not None and self.confidence != Confidence.FAILED
+
+    @property
+    def date(self) -> Optional[datetime.date]:
+        """Return just the date portion, if parsed."""
+        return self.parsed.date() if self.parsed else None
+
+    @property
+    def iso(self) -> Optional[str]:
+        """Return ISO 8601 string, if parsed."""
+        return self.parsed.isoformat() if self.parsed else None
+
+
+@dataclass
+class FormatDetectionResult:
+    """Result of detecting the date format for a batch of values.
+
+    Attributes:
+        format: The most likely format, or None if detection failed.
+        confidence: Overall confidence in the detected format.
+        ambiguities: List of ambiguity types found.
+        candidates: All candidate formats considered, with match counts.
+        sample_size: Number of values analyzed.
+        match_count: Number of values matching the detected format.
+        warnings: Issues found during detection.
+    """
+
+    format: Optional[DateFormat] = None
+    confidence: Confidence = Confidence.FAILED
+    ambiguities: list[AmbiguityType] = field(default_factory=list)
+    candidates: list[FormatCandidate] = field(default_factory=list)
+    sample_size: int = 0
+    match_count: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def is_ambiguous(self) -> bool:
+        """True if ambiguity was detected."""
+        return len(self.ambiguities) > 0
+
+    @property
+    def match_ratio(self) -> float:
+        """Fraction of values matching the detected format."""
+        if self.sample_size == 0:
+            return 0.0
+        return self.match_count / self.sample_size
+
+
+@dataclass
+class FormatCandidate:
+    """A candidate format with its match statistics.
+
+    Attributes:
+        format: The candidate date format.
+        match_count: How many values match this format.
+        sample_size: Total values tested.
+        confidence: Confidence if this format were chosen.
+    """
+
+    format: DateFormat
+    match_count: int = 0
+    sample_size: int = 0
+    confidence: Confidence = Confidence.FAILED
+
+    @property
+    def match_ratio(self) -> float:
+        if self.sample_size == 0:
+            return 0.0
+        return self.match_count / self.sample_size
+
+
+@dataclass
+class BatchResult:
+    """Result of parsing a batch of date values.
+
+    Attributes:
+        results: Per-value parse results.
+        detected_format: The format used (detected or specified).
+        total: Total number of values in the batch.
+        parsed_count: Number successfully parsed.
+        failed_count: Number that failed to parse.
+        warnings: Batch-level warnings.
+        format_detection: Full detection result, if detection was performed.
+    """
+
+    results: list[DateResult] = field(default_factory=list)
+    detected_format: Optional[DateFormat] = None
+    total: int = 0
+    parsed_count: int = 0
+    failed_count: int = 0
+    warnings: list[str] = field(default_factory=list)
+    format_detection: Optional[FormatDetectionResult] = None
+
+    @property
+    def ok(self) -> bool:
+        """True if all values were parsed successfully."""
+        return self.failed_count == 0 and self.total > 0
+
+    @property
+    def success_ratio(self) -> float:
+        """Fraction of values successfully parsed."""
+        if self.total == 0:
+            return 0.0
+        return self.parsed_count / self.total
+
+    @property
+    def dates(self) -> list[Optional[datetime.datetime]]:
+        """Extract just the parsed datetimes (None for failures)."""
+        return [r.parsed for r in self.results]
+
+    @property
+    def iso_strings(self) -> list[Optional[str]]:
+        """Extract ISO 8601 strings (None for failures)."""
+        return [r.iso for r in self.results]
+
+    @property
+    def failed(self) -> list[DateResult]:
+        """Return only the failed results."""
+        return [r for r in self.results if not r.ok]
+
+    @property
+    def succeeded(self) -> list[DateResult]:
+        """Return only the successful results."""
+        return [r for r in self.results if r.ok]

datemonkey/parser.py

@@ -0,0 +1,174 @@
+"""Batch date parser with format lock-in.
+
+Once a format is detected (or specified), it is enforced across all values
+in the batch. Values that don't match are flagged, not silently re-guessed.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any, Optional, Sequence, Union
+
+from .detector import detect_format
+from .excel import EXCEL_SERIAL_FORMAT, parse_excel_serial
+from .formats import could_be_excel_serial
+from .models import (
+    AmbiguityType,
+    BatchResult,
+    Confidence,
+    DateFormat,
+    DateResult,
+    FormatDetectionResult,
+)
+
+
+def _parse_single(
+    value: Any,
+    fmt: DateFormat,
+    row_index: Optional[int] = None,
+) -> DateResult:
+    """Parse a single value with a locked-in format."""
+    # Handle blanks/None
+    if value is None or (isinstance(value, str) and value.strip() == ""):
+        return DateResult(
+            original=value,
+            confidence=Confidence.FAILED,
+            format_used=fmt,
+            warnings=["Blank or None value."],
+            row_index=row_index,
+        )
+
+    s = str(value).strip()
+
+    # Excel serial path
+    if fmt == EXCEL_SERIAL_FORMAT:
+        return parse_excel_serial(value, row_index=row_index)
+
+    # Standard strftime path
+    try:
+        parsed = datetime.datetime.strptime(s, fmt.pattern)
+        return DateResult(
+            original=value,
+            parsed=parsed,
+            format_used=fmt,
+            confidence=Confidence.HIGH,
+            row_index=row_index,
+        )
+    except (ValueError, OverflowError):
+        warnings = [f"Value does not match format {fmt.label} ({fmt.pattern})."]
+        # Hint if it looks like an Excel serial
+        if could_be_excel_serial(s):
+            warnings.append("This looks like an Excel serial date number.")
+        return DateResult(
+            original=value,
+            confidence=Confidence.FAILED,
+            format_used=fmt,
+            warnings=warnings,
+            row_index=row_index,
+        )
+
+
+def parse_dates(
+    values: Sequence[Any],
+    *,
+    format: Optional[Union[DateFormat, str]] = None,
+    locale_preference: Optional[str] = None,
+    strict: bool = False,
+) -> BatchResult:
+    """Parse a batch of date values.
+
+    If ``format`` is provided, it is used directly (format lock-in).
+    If not, the format is auto-detected from the batch.
+
+    Args:
+        values: Sequence of date-like values (strings, ints, floats, None).
+        format: A DateFormat or strftime pattern string to enforce.
+            If None, auto-detect from the values.
+        locale_preference: Hint for resolving DD/MM vs MM/DD ambiguity
+            during auto-detection. "us" for MM/DD, "eu" for DD/MM.
+        strict: If True, treat any ambiguity as a failure (don't parse
+            ambiguous values, report them as errors).
+
+    Returns:
+        BatchResult containing per-value results, detected format,
+        and batch-level statistics.
+    """
+    if not values:
+        return BatchResult(warnings=["Empty input: no values to parse."])
+
+    detection_result: Optional[FormatDetectionResult] = None
+    resolved_format: Optional[DateFormat] = None
+
+    # Resolve the format to use
+    if format is not None:
+        if isinstance(format, str):
+            if format == "EXCEL_SERIAL":
+                resolved_format = EXCEL_SERIAL_FORMAT
+            else:
+                resolved_format = DateFormat(
+                    pattern=format,
+                    label=f"Custom ({format})",
+                )
+        else:
+            resolved_format = format
+    else:
+        # Auto-detect
+        detection_result = detect_format(
+            values,
+            locale_preference=locale_preference,
+        )
+        resolved_format = detection_result.format
+
+    if resolved_format is None:
+        return BatchResult(
+            total=len(values),
+            warnings=["Could not determine date format."],
+            format_detection=detection_result,
+        )
+
+    # In strict mode, refuse to parse if ambiguous
+    if strict and detection_result and detection_result.is_ambiguous:
+        if AmbiguityType.DAY_MONTH_SWAP in detection_result.ambiguities:
+            return BatchResult(
+                total=len(values),
+                detected_format=resolved_format,
+                warnings=[
+                    "Strict mode: refusing to parse due to DD/MM vs MM/DD "
+                    "ambiguity. Provide a format or locale_preference to resolve."
+                ]
+                + detection_result.warnings,
+                format_detection=detection_result,
+            )
+
+    # Parse each value with the locked-in format
+    results: list[DateResult] = []
+    parsed_count = 0
+    failed_count = 0
+    batch_warnings: list[str] = []
+
+    for i, v in enumerate(values):
+        result = _parse_single(v, resolved_format, row_index=i)
+        results.append(result)
+        if result.ok:
+            parsed_count += 1
+        else:
+            failed_count += 1
+
+    if detection_result:
+        batch_warnings.extend(detection_result.warnings)
+
+    if failed_count > 0:
+        batch_warnings.append(
+            f"{failed_count}/{len(values)} values failed to parse "
+            f"with format {resolved_format.label}."
+        )
+
+    return BatchResult(
+        results=results,
+        detected_format=resolved_format,
+        total=len(values),
+        parsed_count=parsed_count,
+        failed_count=failed_count,
+        warnings=batch_warnings,
+        format_detection=detection_result,
+    )

datemonkey-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: datemonkey
+Version: 0.1.0
+Summary: Batch date parsing with ambiguity detection, confidence scores, and format lock-in.
+Author-email: RexBytes <pythonic@rexbytes.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/RexBytes/datemonkey
+Project-URL: Repository, https://github.com/RexBytes/datemonkey
+Project-URL: Issues, https://github.com/RexBytes/datemonkey/issues
+Keywords: date,parsing,ambiguity,detection,batch,excel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# datemonkey
+
+Batch date parsing with ambiguity detection, confidence scores, and format lock-in.
+
+**The problem:** `dateutil.parser.parse("01/02/03")` silently guesses and is often wrong. DD/MM vs MM/DD ambiguity corrupts joins, aggregations, and reports. datemonkey detects ambiguity and tells you about it instead of guessing.
+
+## Install
+
+```bash
+pip install datemonkey
+```
+
+## Quick Start
+
+### Detect format from a column of values
+
+```python
+from datemonkey import detect_format
+
+result = detect_format(["15/03/2024", "20/04/2024", "25/12/2024"])
+print(result.format.label)      # "European date (DD/MM/YYYY)"
+print(result.confidence)         # Confidence.HIGH
+print(result.is_ambiguous)       # False — day > 12 resolves it
+```
+
+### Ambiguity detection
+
+```python
+result = detect_format(["01/02/2024", "03/04/2024", "05/06/2024"])
+print(result.is_ambiguous)       # True
+print(result.ambiguities)        # [AmbiguityType.DAY_MONTH_SWAP]
+print(result.warnings)
+# ["Ambiguous: cannot distinguish US date (MM/DD/YYYY) from European date (DD/MM/YYYY) ..."]
+```
+
+### Resolve ambiguity with locale preference
+
+```python
+result = detect_format(["01/02/2024", "03/04/2024"], locale_preference="eu")
+print(result.format.label)       # "European date (DD/MM/YYYY)"
+```
+
+### Parse a batch of dates
+
+```python
+from datemonkey import parse_dates
+
+batch = parse_dates(["2024-03-15", "2024-04-20", "2024-12-25"])
+print(batch.ok)                  # True
+print(batch.dates)               # [datetime(2024,3,15), datetime(2024,4,20), datetime(2024,12,25)]
+print(batch.iso_strings)         # ["2024-03-15T00:00:00", ...]
+```
+
+### Format lock-in
+
+```python
+from datemonkey import parse_dates, ISO_8601
+
+batch = parse_dates(["2024-03-15", "03/15/2024"], format=ISO_8601)
+print(batch.results[0].ok)       # True  — matches ISO
+print(batch.results[1].ok)       # False — doesn't match, flagged not re-guessed
+```
+
+### Strict mode
+
+```python
+batch = parse_dates(["01/02/2024", "03/04/2024"], strict=True)
+print(batch.parsed_count)        # 0 — refuses to parse ambiguous data
+print(batch.warnings)            # ["Strict mode: refusing to parse due to DD/MM vs MM/DD ambiguity..."]
+```
+
+### Excel serial dates
+
+```python
+from datemonkey import parse_dates, excel_serial_to_datetime
+
+# Single value
+dt = excel_serial_to_datetime(45292)  # datetime(2024, 1, 1)
+
+# Batch — auto-detected
+batch = parse_dates(["45292", "45293", "45294"])
+print(batch.detected_format.label)  # "Excel serial date number"
+```
+
+### Per-value results
+
+```python
+batch = parse_dates(["2024-03-15", "garbage", "2024-12-25"], format="%Y-%m-%d")
+for r in batch.results:
+    print(f"{r.original:20s} ok={r.ok}  parsed={r.iso}  warnings={r.warnings}")
+# 2024-03-15           ok=True   parsed=2024-03-15T00:00:00  warnings=[]
+# garbage              ok=False  parsed=None                  warnings=[...]
+# 2024-12-25           ok=True   parsed=2024-12-25T00:00:00  warnings=[]
+```
+
+## CLI
+
+```bash
+# Detect format
+datemonkey detect "15/03/2024" "20/04/2024" "25/12/2024"
+
+# Detect with JSON output
+datemonkey detect --json "01/02/2024" "03/04/2024"
+
+# Parse dates
+datemonkey parse "2024-03-15" "2024-04-20"
+
+# Parse from CSV file (column 2, skip header)
+datemonkey parse --file data.csv --column 2 --skip-header
+
+# Parse with explicit format
+datemonkey parse --format "%d-%m-%Y" "15-03-2024"
+
+# Parse in strict mode
+datemonkey parse --strict "01/02/2024" "03/04/2024"
+
+# List known formats
+datemonkey formats
+```
+
+## API Reference
+
+### `detect_format(values, *, locale_preference=None, formats=None) -> FormatDetectionResult`
+
+Analyze a batch and determine the most likely format, reporting ambiguity.
+
+- **values**: List of date-like values (strings, ints, floats, None)
+- **locale_preference**: `"us"` for MM/DD, `"eu"` for DD/MM (only used when data alone can't resolve)
+- **formats**: Custom list of `DateFormat` objects to test
+
+### `parse_dates(values, *, format=None, locale_preference=None, strict=False) -> BatchResult`
+
+Parse a batch with format lock-in.
+
+- **format**: A `DateFormat` object or strftime string. If None, auto-detected.
+- **strict**: If True, refuse to parse when DD/MM vs MM/DD is ambiguous.
+
+### `excel_serial_to_datetime(serial) -> datetime | None`
+
+Convert an Excel serial date number to a Python datetime.
+
+### Result Objects
+
+| Object | Key Properties |
+|---|---|
+| `FormatDetectionResult` | `.format`, `.confidence`, `.is_ambiguous`, `.ambiguities`, `.candidates`, `.warnings` |
+| `BatchResult` | `.ok`, `.results`, `.detected_format`, `.dates`, `.iso_strings`, `.failed`, `.succeeded`, `.success_ratio` |
+| `DateResult` | `.ok`, `.original`, `.parsed`, `.date`, `.iso`, `.confidence`, `.warnings`, `.row_index` |
+
+### Confidence Levels
+
+| Level | Meaning |
+|---|---|
+| `HIGH` | Unambiguous parse, format is certain |
+| `MEDIUM` | Likely correct, minor ambiguity (e.g. two-digit year) |
+| `LOW` | Ambiguous — DD/MM vs MM/DD unresolved, or poor match ratio |
+| `FAILED` | Could not parse or detect |
+
+## Design
+
+- **Batch-first**: Designed for columns of data, not single strings
+- **No silent guessing**: Ambiguity is reported, not hidden
+- **Format lock-in**: Once detected, the format is enforced — violations are flagged
+- **Structured results**: Every parse returns confidence scores and warnings
+- **Zero dependencies**: Pure Python, stdlib only
+
+## Built for LLMs
+
+datemonkey is designed to work well as a tool for large language models. Date parsing is a common source of silent errors in LLM-driven data pipelines — ambiguous formats lead to wrong guesses, wasted tokens on retries, and broken downstream logic. datemonkey reduces that complexity: a single call returns a structured result with the detected format, confidence level, and any ambiguities — no multi-step prompting or validation loops required. Fewer tokens in, reliable answers out.
+
+## License
+
+MIT