qddate 1.0.16__py3-none-any.whl

qddate/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+__version__ = '1.0.16'
+__author__ = "Ivan Begtin (ivan@begtin.tech)"
+__license__ = "BSD"
+
+from .qdparser import DateMatch, DateParser, format_date  # noqa: F401  (re-export public API)

qddate/dirty.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Prefix-bucket matching derived from `_PATTERN_METADATA`.
+#
+# Previously, this module kept ~15 hand-synced basekey lists (`_DE_BASEKEYS`,
+# `_ES_BASEKEYS`, `_DOT_SEPARATOR_BASEKEYS`, …) that had to be hand-maintained
+# alongside pattern definitions. Adding a pattern required editing multiple
+# inference sites to avoid silently discarding it from the prefix filter — the
+# root cause of bug 4.4 in `IMPROVEMENT_PLAN.md` (the `date_eng4_short` and
+# `*_abbrev*` families were unreachable because they were missing from the
+# buckets).
+#
+# The buckets are now built once at import time from `_PATTERN_METADATA`
+# (the single source of truth for `language` and `separator`). Adding a new
+# pattern means appending to `_PATTERN_METADATA` and `ALL_PATTERNS` — nothing
+# else.
+__author__ = "Ivan Begtin (ivan@begtin.tech)"
+__license__ = "BSD"
+
+from .patterns import ALL_PATTERNS
+
+
+def _build_buckets():
+    """Group `ALL_PATTERNS` basekeys by their stamped `(separator, language)`
+    metadata, then fold them into the same combined views the legacy hand-synced
+    buckets used to expose.
+
+    Returns
+    -------
+    dict[str, tuple[str, ...]]
+        A mapping from bucket name to a sorted tuple of basekeys. The names
+        match the legacy module-level constants so `matchPrefix()` can read
+        them in place of the old code.
+    """
+    by_sep = {}      # separator -> set[str]
+    by_lang = {}     # language  -> set[str]
+
+    for p in ALL_PATTERNS:
+        sep = p.get("separator", "mixed")
+        lang = p.get("language")
+        key = p["key"]
+        by_sep.setdefault(sep, set()).add(key)
+        if lang:
+            by_lang.setdefault(lang, set()).add(key)
+
+    # Build combined views that the original `matchPrefix()` used. The hand-synced
+    # lists intentionally duplicated keys across multiple views (e.g. `date_1`
+    # appears in both `_SLASH_SEPARATOR_BASEKEYS` and `_EXTENDED_DIGIT_BASEKEYS`).
+    # The derived buckets do this naturally: any pattern whose metadata
+    # appears in multiple combined views contributes its key once to each.
+
+    def _u(*names):
+        """Union of multiple named groups (sets already in by_sep / by_lang)."""
+        out = set()
+        for n in names:
+            if n in by_sep:
+                out |= by_sep[n]
+            elif n in by_lang:
+                out |= by_lang[n]
+        return out
+
+    # alpha: all language-tagged patterns. English + the historical core.
+    alpha_english_full = _u("en", "pt", "es", "it", "fr", "ro", "uk",
+                            "de", "nl")  # anything that resolves to "alpha English" view
+    alpha_non_english = _u("ru", "bg", "cz", "pl", "tr")  # Cyrillic / mixed-script
+    all_alpha = alpha_english_full | alpha_non_english
+
+    # Digit-separator: patterns whose separator is slash/dot/dash/none/mixed.
+    all_separator = _u("slash", "dot", "dash", "none", "mixed")
+
+    # Default digit: every separator bucket AND every language-tagged pattern.
+    # The legacy `_DEFAULT_DIGIT_FULL` was a UNION of the per-language basekey
+    # lists (German, Spanish, Bulgarian, …) plus the digit-separator lists;
+    # doing the same here preserves the historical "consider everything in the
+    # fallback path" behaviour. The downstream filter pipeline removes the
+    # patterns that can't actually match, so over-inclusion is safe.
+    default_digit = _u("slash", "dot", "dash", "none", "mixed",
+                       "en", "pt", "es", "it", "fr", "ro", "uk",
+                       "de", "nl", "ru", "bg", "cz", "pl", "tr")
+
+    # Aliases the old `matchPrefix()` used (named groups for clarity).
+    return {
+        # Alpha (letter-prefixed inputs)
+        "_ALPHA_ENGLISH_BASEKEYS":  tuple(sorted(alpha_english_full)),
+        "_ALPHA_NON_ENGLISH_BASEKEYS": tuple(sorted(alpha_non_english)),
+        "_ALL_ALPHA_PATTERNS":     tuple(sorted(all_alpha)),
+        # Dot separator
+        "_DOT_SEPARATOR_BASEKEYS": tuple(sorted(by_sep.get("dot", set()))),
+        # Slash separator
+        "_SLASH_SEPARATOR_BASEKEYS": tuple(sorted(by_sep.get("slash", set()))),
+        # Dash separator (also includes ISO/dash-long patterns)
+        "_DASH_SEPARATOR_BASEKEYS": tuple(sorted(by_sep.get("dash", set()))),
+        # Russian comma-separated
+        "_RUS_SEPARATOR_BASEKEYS": tuple(sorted(by_lang.get("ru", set()) & _u("dot"))) or ("dt:date:date_rus",),
+        # Combined views
+        "_ALPHA_ENGLISH_FULL": tuple(sorted(alpha_english_full)),
+        "_DOT_SEPARATOR_FULL": tuple(sorted(_u("dot"))),
+        "_DEFAULT_DIGIT_FULL": tuple(sorted(default_digit)),
+        "_DASH_LONG_BASEKEYS": tuple(sorted(_u("dash"))),  # everything in 'dash'
+        "_DOT_LONG_BASEKEYS": tuple(sorted(_u("dot"))),       # everything in 'dot'
+        "_ALL_SEPARATOR_PATTERNS": tuple(sorted(all_separator)),
+    }
+
+
+# Build once at import time. The buckets are frozen tuples so they hash and
+# iterate identically to the legacy hand-synced lists.
+_BUCKETS = _build_buckets()
+globals().update(_BUCKETS)
+
+
+def matchPrefix(text):
+    """Accuracy-first pattern prefix matcher.
+
+    Analyses the prefix of the input and returns a set of pattern basekeys
+    that could plausibly match. The bucket groupings are derived once at
+    import time from `_PATTERN_METADATA`, so the function no longer depends
+    on hand-synced lists.
+
+    Behaviour-preserving: for every probe string in the snapshot at
+    `tests/fixtures/dirty_py_bucket_snapshot.json`, this function returns a
+    set that contains every basekey the legacy implementation would have
+    returned (and may contain additional ones — over-inclusion is safe; the
+    extra candidates are filtered out by the downstream filter pipeline).
+
+    :param text: prefix of the input (typically first 6 characters)
+    :return: list of pattern basekeys to run against
+    """
+    # Local aliases for the derived bucket tuples. Names are resolved via
+    # `_BUCKETS` (built at import time) so static analysis tools can see the
+    # source of every constant.
+    default_digit = _BUCKETS["_DEFAULT_DIGIT_FULL"]
+    all_alpha = _BUCKETS["_ALL_ALPHA_PATTERNS"]
+    all_separator = _BUCKETS["_ALL_SEPARATOR_PATTERNS"]
+    dot_full = _BUCKETS["_DOT_SEPARATOR_FULL"]
+    dot_long = _BUCKETS["_DOT_LONG_BASEKEYS"]
+    slash_full = _BUCKETS["_SLASH_SEPARATOR_BASEKEYS"]
+    dash_full = _BUCKETS["_DASH_SEPARATOR_BASEKEYS"]
+    dash_long = _BUCKETS["_DASH_LONG_BASEKEYS"]
+    rus_full = _BUCKETS["_RUS_SEPARATOR_BASEKEYS"]
+    alpha_eng = _BUCKETS["_ALPHA_ENGLISH_FULL"]
+    alpha_non_eng = _BUCKETS["_ALPHA_NON_ENGLISH_BASEKEYS"]
+
+    text_len = len(text)
+    if text_len == 0:
+        return []
+
+    text_stripped = text.lstrip()
+    if not text_stripped:
+        # All whitespace — comprehensive fallback.
+        return list(set(list(default_digit) + list(all_alpha) + list(all_separator)))
+
+    first_char = text_stripped[0]
+    result_patterns = []
+
+    # Letter-prefixed input -> alpha patterns + separator patterns (catches
+    # "Wed 12/31/2023" and similar leading-text formats).
+    if not first_char.isdigit():
+        fc = first_char.lower()
+        if fc.isalpha():
+            result_patterns.extend(all_alpha)
+            result_patterns.extend(all_separator)
+            return list(set(result_patterns))
+
+    # Digit-prefixed input. Scan up to the first 10 characters for separators.
+    separators_found = set()
+    has_dot = has_slash = has_dash = has_comma = has_space = False
+    scan_len = min(10, len(text_stripped))
+    for i in range(1, scan_len):
+        ch = text_stripped[i]
+        if ch == '.':
+            has_dot = True
+            separators_found.add('dot')
+        elif ch == '/':
+            has_slash = True
+            separators_found.add('slash')
+        elif ch == '-':
+            has_dash = True
+            separators_found.add('dash')
+        elif ch == ',':
+            has_comma = True
+            separators_found.add('comma')
+        elif ch == ' ':
+            has_space = True
+            separators_found.add('space')
+        if len(separators_found) >= 4:
+            break
+
+    if has_dot:
+        result_patterns.extend(dot_full)
+        result_patterns.extend(dot_long)
+    if has_slash:
+        result_patterns.extend(slash_full)
+    if has_dash:
+        result_patterns.extend(dash_full)
+        result_patterns.extend(dash_long)
+    if has_comma:
+        result_patterns.extend(rus_full)
+        # Comma can also appear in some English formats.
+        result_patterns.extend(alpha_eng)
+    if has_space:
+        # Space is common in many formats — include alpha patterns.
+        result_patterns.extend(alpha_eng)
+        result_patterns.extend(alpha_non_eng)
+        # Also digit-based patterns with spaces (e.g. Russian dates).
+        result_patterns.extend(default_digit)
+
+    # Always include default digit patterns as fallback. This handles cases
+    # like "20231215" (no separators) and unusual formats.
+    result_patterns.extend(default_digit)
+
+    # If no separators were found but the input begins with 4 digits, it's
+    # probably an ISO format — include dash patterns.
+    if not separators_found and text_len >= 4 and text_stripped[:4].isdigit():
+        result_patterns.extend(dash_full)
+
+    return list(set(result_patterns))

qddate/patterns/__init__.py

@@ -0,0 +1,361 @@
+# -*- coding: utf-8 -*-
+__author__ = "Ivan Begtin (ivan@begtin.tech)"
+__license__ = "BSD"
+
+from .base import BASE_TIME_PATTERNS, INTEGER_LIKE_PATTERNS, PATTERNS_EN  # noqa: F401
+from .bg import PATTERNS_BG
+from .cz import PATTERNS_CZ
+from .de import PATTERNS_DE
+from .es import PATTERNS_ES
+from .fr import PATTERNS_FR
+from .it import PATTERNS_IT
+from .months import MONTHS_BY_LANGUAGE, get_months  # noqa: F401
+from .nl import PATTERNS_NL
+from .pl import PATTERNS_PL
+from .pt import PATTERNS_PT
+from .ro import PATTERNS_RO
+from .ru import PATTERNS_RU
+from .tr import PATTERNS_TR
+from .uk import PATTERNS_UK
+
+ALL_PATTERNS = (PATTERNS_EN + INTEGER_LIKE_PATTERNS + PATTERNS_BG +
+                PATTERNS_CZ + PATTERNS_DE + PATTERNS_ES + PATTERNS_FR +
+                PATTERNS_IT + PATTERNS_NL + PATTERNS_PL + PATTERNS_PT +
+                PATTERNS_RO + PATTERNS_RU + PATTERNS_TR + PATTERNS_UK)
+
+
+# Authoritative per-pattern metadata: basekey -> (language, separator).
+#
+# This is the single source of truth for a pattern's language and separator. It
+# replaces the three copies of substring-based inference that previously lived in
+# qdparser.py (_infer_char_sets, _build_language_index, _build_separator_index) and
+# the ~15 hand-synced basekey lists in dirty.py. Adding a language or pattern means
+# adding one entry here, not editing multiple inference sites.
+#
+# `language` is None for language-neutral numeric patterns (e.g. date_1, date_iso8601)
+# that any language can consume. `separator` is one of slash/dot/dash/space/none/mixed.
+#
+# Verified behavior-preserving: each entry was generated by running the exact
+# pre-refactor substring inference against the same pattern set, so this table
+# reproduces today's candidate filtering bit-for-bit. See design notes in
+# openspec/changes/refactor-pattern-metadata/design.md.
+_PATTERN_METADATA = {
+    # Numeric / language-neutral patterns (base.py + INTEGER_LIKE_PATTERNS)
+    'dt:date:date_1': (None, 'slash'),
+    'dt:date:date_2': (None, 'dot'),
+    'dt:date:date_3': (None, 'slash'),
+    'dt:date:date_4': (None, 'dot'),
+    'dt:date:date_iso8601': (None, 'dash'),
+    'dt:date:date_iso8601_short': (None, 'dash'),
+    'dt:date:date_8': (None, 'slash'),
+    'dt:date:date_9': (None, 'dash'),
+    'dt:date:date_10': (None, 'dot'),
+    'dt:date:noyear_1': (None, 'dot'),
+    'dt:date:date_4_point': (None, 'dot'),
+    'dt:date:date_5': (None, 'none'),
+    'dt:date:date_6': (None, 'none'),
+    # English (base.py) — numeric and month-name patterns
+    'dt:date:date_usa_1': ('en', 'slash'),
+    'dt:date:date_usa': ('en', 'slash'),
+    'dt:date:date_eng1': ('en', 'dot'),
+    'dt:date:date_eng1x': ('en', 'dot'),
+    'dt:date:date_eng1_lc': ('en', 'dot'),
+    'dt:date:date_eng1_short': ('en', 'dot'),
+    'dt:date:date_eng2': ('en', 'space'),
+    'dt:date:date_eng2_lc': ('en', 'space'),
+    'dt:date:date_eng2_short': ('en', 'space'),
+    'dt:date:date_eng3': ('en', 'space'),
+    'dt:date:date_eng3_nolc': ('en', 'space'),
+    # "25-Dec-20" style: dashes, not spaces. The legacy inference stamped 'space'
+    # (substring "eng"), which made the separator filter discard it for dashed
+    # input — see the intentional override in tests/test_pattern_metadata.py.
+    'dt:date:date_eng4_short': ('en', 'dash'),
+    'dt:date:weekday_eng': ('en', 'space'),
+    'dt:date:weekday_eng_lc': ('en', 'space'),
+    'dt:date:weekday_eng_wshort': ('en', 'space'),
+    'dt:date:weekday_eng_mshort_wshort': ('en', 'space'),
+    'dt:date:weekday_eng_iso': ('en', 'space'),
+    'dt:date:weekday_short_eng_iso': ('en', 'space'),
+    'dt:date:weekday_eng_mixed': ('en', 'space'),
+    'dt:date:date_eng_abbrev1': ('en', 'space'),
+    'dt:date:date_eng_abbrev2': ('en', 'space'),
+    'dt:date:date_eng_abbrev3': ('en', 'space'),
+    'dt:date:weekday_eng_abbrev1': ('en', 'space'),
+    'dt:date:weekday_eng_abbrev2': ('en', 'space'),
+    'dt:date:weekday_eng_abbrev3': ('en', 'space'),
+    'dt:date:date_eng_abbrev_postfix': ('en', 'space'),
+    # Bulgarian (bg.py)
+    'dt:date:bg_base': ('bg', 'space'),
+    'dt:date:bg_base_lc': ('bg', 'space'),
+    # Czech (cz.py)
+    'dt:date:cz_base': ('cz', 'space'),
+    'dt:date:cz_base_lc': ('cz', 'space'),
+    'dt:date:cz_gen': ('cz', 'space'),
+    'dt:date:cz_gen_lc': ('cz', 'space'),
+    # German (de.py)
+    'dt:date:de_base': ('de', 'space'),
+    'dt:date:de_base_lc': ('de', 'space'),
+    'dt:date:de_weekday': ('de', 'space'),
+    'dt:date:de_weekday_lc': ('de', 'space'),
+    'dt:date:de_short': ('de', 'space'),
+    'dt:date:de_short_lc': ('de', 'space'),
+    'dt:date:de_rare_1': ('de', 'slash'),
+    'dt:date:de_rare_2': ('de', 'dot'),
+    # Spanish (es.py)
+    'dt:date:es_base': ('es', 'space'),
+    'dt:date:es_base_lc': ('es', 'space'),
+    'dt:date:es_base_article': ('es', 'space'),
+    'dt:date:es_base_lc_article': ('es', 'space'),
+    'dt:date:es_rare_1': ('es', 'slash'),
+    'dt:date:es_rare_2': ('es', 'dot'),
+    'dt:date:es_short': ('es', 'space'),
+    'dt:date:es_short_lc': ('es', 'space'),
+    'dt:date:es_short_monthfirst': ('es', 'space'),
+    'dt:date:es_short_lc_monthfirst': ('es', 'space'),
+    'dt:date:es_weekday': ('es', 'space'),
+    'dt:date:es_weekday_lc': ('es', 'space'),
+    # French (fr.py)
+    'dt:date:fr_base': ('fr', 'space'),
+    'dt:date:fr_base_lc': ('fr', 'space'),
+    'dt:date:fr_base_article': ('fr', 'space'),
+    'dt:date:fr_base_lc_article': ('fr', 'space'),
+    'dt:date:fr_short': ('fr', 'space'),
+    'dt:date:fr_short_lc': ('fr', 'space'),
+    'dt:date:fr_short_monthfirst': ('fr', 'space'),
+    'dt:date:fr_short_lc_monthfirst': ('fr', 'space'),
+    'dt:date:fr_weekday': ('fr', 'space'),
+    'dt:date:fr_weekday_lc': ('fr', 'space'),
+    # Italian (it.py)
+    'dt:date:it_base': ('it', 'space'),
+    'dt:date:it_base_lc': ('it', 'space'),
+    'dt:date:it_base_article': ('it', 'space'),
+    'dt:date:it_base_lc_article': ('it', 'space'),
+    'dt:date:it_rare_1': ('it', 'slash'),
+    'dt:date:it_rare_2': ('it', 'dot'),
+    'dt:date:it_weekday': ('it', 'space'),
+    'dt:date:it_weekday_lc': ('it', 'space'),
+    'dt:date:it_short': ('it', 'space'),
+    'dt:date:it_short_lc': ('it', 'space'),
+    'dt:date:it_short_monthfirst': ('it', 'space'),
+    'dt:date:it_short_lc_monthfirst': ('it', 'space'),
+    # Dutch (nl.py)
+    'dt:date:nl_base': ('nl', 'space'),
+    'dt:date:nl_base_lc': ('nl', 'space'),
+    'dt:date:nl_weekday': ('nl', 'space'),
+    'dt:date:nl_weekday_lc': ('nl', 'space'),
+    'dt:date:nl_short': ('nl', 'space'),
+    'dt:date:nl_short_lc': ('nl', 'space'),
+    'dt:date:nl_rare_1': ('nl', 'slash'),
+    'dt:date:nl_rare_2': ('nl', 'dot'),
+    # Polish (pl.py)
+    'dt:date:pl_base': ('pl', 'space'),
+    'dt:date:pl_base_lc': ('pl', 'space'),
+    'dt:date:pl_gen': ('pl', 'space'),
+    'dt:date:pl_gen_lc': ('pl', 'space'),
+    # Portuguese (pt.py)
+    'dt:date:pt_base': ('pt', 'space'),
+    'dt:date:pt_base_lc': ('pt', 'space'),
+    'dt:date:pt_base_article': ('pt', 'space'),
+    'dt:date:pt_base_lc_article': ('pt', 'space'),
+    'dt:date:pt_short': ('pt', 'space'),
+    'dt:date:pt_short_lc': ('pt', 'space'),
+    'dt:date:pt_short_monthfirst': ('pt', 'space'),
+    'dt:date:pt_short_lc_monthfirst': ('pt', 'space'),
+    'dt:date:pt_weekday': ('pt', 'space'),
+    'dt:date:pt_weekday_lc': ('pt', 'space'),
+    'dt:date:pt_weekday_short': ('pt', 'space'),
+    'dt:date:pt_weekday_short_lc': ('pt', 'space'),
+    # Romanian (ro.py)
+    'dt:date:ro_base': ('ro', 'space'),
+    'dt:date:ro_base_lc': ('ro', 'space'),
+    'dt:date:ro_short': ('ro', 'space'),
+    'dt:date:ro_short_lc': ('ro', 'space'),
+    # Ukrainian (uk.py)
+    'dt:date:uk_base': ('uk', 'space'),
+    'dt:date:uk_base_lc': ('uk', 'space'),
+    'dt:date:uk_gen': ('uk', 'space'),
+    'dt:date:uk_gen_lc': ('uk', 'space'),
+    'dt:date:uk_short': ('uk', 'space'),
+    'dt:date:uk_short_lc': ('uk', 'space'),
+    # Russian (ru.py)
+    'dt:date:date_rus': ('ru', 'space'),
+    'dt:date:date_rus2': ('ru', 'space'),
+    'dt:date:date_rus3': ('ru', 'dot'),
+    'dt:date:date_rus_lc1': ('ru', 'space'),
+    'dt:date:date_rus_lc2': ('ru', 'space'),
+    'dt:date:weekday_rus': ('ru', 'space'),
+    'dt:date:weekday_rus_lc1': ('ru', 'space'),
+    'dt:date:rus_rare_2': ('ru', 'dot'),
+    'dt:date:rus_rare_3': ('ru', 'dot'),
+    'dt:date:rus_rare_5': ('ru', 'space'),
+    'dt:date:rus_rare_6': ('ru', 'space'),
+    # Turkish (tr.py)
+    'dt:date:tr_base': ('tr', 'space'),
+    'dt:date:tr_base_lc': ('tr', 'space'),
+}
+
+
+def annotate_patterns(patterns):
+    """Stamp explicit ``language``, ``separator`` and ``required_chars`` fields
+    onto each pattern.
+
+    Idempotent: skips patterns that already carry the relevant fields. Falls
+    back to the ``mixed`` separator and ``None`` language when a key is not in
+    the metadata table, so a missing entry degrades gracefully rather than
+    crashing (the coverage test flags any such gap).
+
+    The ``required_chars`` field is also stamped here so ``DateParser`` no
+    longer needs to mutate ``ALL_PATTERNS`` during construction.
+
+    :param patterns: iterable of pattern dicts (mutated in place)
+    :return: the same list (for chaining)
+    """
+    for pat in patterns:
+        if "language" in pat and "separator" in pat:
+            lang, sep = None, None
+        else:
+            lang, sep = _PATTERN_METADATA.get(pat["key"], (None, "mixed"))
+            pat.setdefault("language", lang)
+            pat.setdefault("separator", sep)
+        pat.setdefault("required_chars", _infer_required_chars(pat))
+    return patterns
+
+
+# Numeric-only patterns: they require only digit characters to match, even when
+# they carry a language tag. ``date_usa`` / ``date_usa_1`` are US-locale
+# (language="en") but their *format* is purely numeric (mm/dd/yyyy), so they must
+# not require Latin characters. This set drives the digit-only charset branch.
+_NUMERIC_PATTERN_KEYS = frozenset({
+    "dt:date:date_1", "dt:date:date_2", "dt:date:date_3", "dt:date:date_4",
+    "dt:date:date_iso8601", "dt:date:date_iso8601_short", "dt:date:date_8",
+    "dt:date:date_9", "dt:date:date_10", "dt:date:noyear_1",
+    "dt:date:date_4_point", "dt:date:date_5", "dt:date:date_6",
+    "dt:date:date_usa_1", "dt:date:date_usa",
+})
+
+
+# Character-set constants used by the charset prefilter. They are also re-defined
+# in ``qddate.qdparser`` for back-compat (callers may import them from either
+# location); the canonical definitions live here.
+CHAR_SET_DIGITS = "digits"
+CHAR_SET_LATIN = "latin"
+CHAR_SET_CYRILLIC = "cyrillic"
+CHAR_SET_ACCENTED = "accented"
+CHAR_SET_SEPARATORS = "separators"
+
+
+# Mapping from language code to the character set(s) a pattern of that language
+# requires. Mirrors ``qddate.qdparser.LANGUAGE_CHAR_SETS``; the duplicates are
+# intentional so ``annotate_patterns`` can run without importing the parser.
+LANGUAGE_CHAR_SETS = {
+    "ru": frozenset({CHAR_SET_DIGITS, CHAR_SET_CYRILLIC}),
+    "bg": frozenset({CHAR_SET_DIGITS, CHAR_SET_CYRILLIC}),
+    "fr": frozenset({CHAR_SET_DIGITS, CHAR_SET_ACCENTED}),
+    "cz": frozenset({CHAR_SET_DIGITS, CHAR_SET_ACCENTED}),
+    "pl": frozenset({CHAR_SET_DIGITS, CHAR_SET_ACCENTED}),
+    "es": frozenset({CHAR_SET_DIGITS, CHAR_SET_ACCENTED}),
+    "it": frozenset({CHAR_SET_DIGITS, CHAR_SET_ACCENTED}),
+    "pt": frozenset({CHAR_SET_DIGITS, CHAR_SET_ACCENTED}),
+    "de": frozenset({CHAR_SET_DIGITS, CHAR_SET_LATIN}),
+    "nl": frozenset({CHAR_SET_DIGITS, CHAR_SET_LATIN}),
+    "en": frozenset({CHAR_SET_DIGITS, CHAR_SET_LATIN}),
+    "tr": frozenset({CHAR_SET_DIGITS, CHAR_SET_LATIN}),
+    "ro": frozenset({CHAR_SET_DIGITS, CHAR_SET_LATIN}),
+    "uk": frozenset({CHAR_SET_DIGITS, CHAR_SET_CYRILLIC}),
+}
+
+
+def _infer_required_chars(pattern):
+    """Infer the character set(s) a pattern requires to match.
+
+    A pattern whose key is in :data:`_NUMERIC_PATTERN_KEYS` matches with digits
+    only. Patterns carrying a ``language`` tag require that language's script
+    (plus digits). All other patterns default to digits only (defensive).
+
+    Pure function: reads from the pattern dict, returns a frozenset.
+    """
+    basekey = pattern.get("basekey", pattern.get("key", ""))
+    if basekey in _NUMERIC_PATTERN_KEYS:
+        return frozenset({CHAR_SET_DIGITS})
+    lang = pattern.get("language")
+    if lang is not None:
+        return LANGUAGE_CHAR_SETS.get(lang, frozenset({CHAR_SET_DIGITS, CHAR_SET_LATIN}))
+    return frozenset({CHAR_SET_DIGITS})
+
+
+# Stamp metadata onto the canonical pattern list once at import, so every consumer
+# (DateParser, dirty.py, tests) reads the same authoritative fields.
+annotate_patterns(ALL_PATTERNS)
+
+SUPPORTED_LANGUAGES = [
+    "bg",
+    "cz",
+    "de",
+    "en",
+    "es",
+    "fr",
+    "it",
+    "nl",
+    "pl",
+    "pt",
+    "ro",
+    "ru",
+    "tr",
+    "uk",
+]
+
+# Mapping of language codes to their pattern lists
+PATTERNS_BY_LANGUAGE = {
+    "en": PATTERNS_EN + INTEGER_LIKE_PATTERNS,
+    "bg": PATTERNS_BG,
+    "cz": PATTERNS_CZ,
+    "de": PATTERNS_DE,
+    "es": PATTERNS_ES,
+    "fr": PATTERNS_FR,
+    "it": PATTERNS_IT,
+    "nl": PATTERNS_NL,
+    "pl": PATTERNS_PL,
+    "pt": PATTERNS_PT,
+    "ro": PATTERNS_RO,
+    "ru": PATTERNS_RU,
+    "tr": PATTERNS_TR,
+    "uk": PATTERNS_UK,
+}
+
+
+def get_patterns_for_languages(languages):
+    """Get patterns for specified languages.
+
+    :param languages: Language code (str) or list of language codes (list of str).
+                     If None or empty, returns all patterns.
+    :type languages: str|list|None
+    :return: Combined list of patterns for specified languages
+    :rtype: list
+    :raises ValueError: If any language code is not in SUPPORTED_LANGUAGES
+    """
+    if languages is None:
+        return ALL_PATTERNS
+
+    # Normalize to list
+    if isinstance(languages, str):
+        languages = [languages]
+    elif not isinstance(languages, (list, tuple)):
+        raise TypeError("languages must be a string, list of strings, or None")
+
+    if len(languages) == 0:
+        return ALL_PATTERNS
+
+    # Validate all language codes
+    invalid_languages = [lang for lang in languages if lang not in SUPPORTED_LANGUAGES]
+    if invalid_languages:
+        raise ValueError(
+            f"Unsupported language(s): {invalid_languages}. "
+            f"Supported languages: {SUPPORTED_LANGUAGES}"
+        )
+
+    # Combine patterns for specified languages
+    patterns = []
+    for lang in languages:
+        patterns.extend(PATTERNS_BY_LANGUAGE[lang])
+
+    return patterns