shevchenko-py 0.1.0__py3-none-any.whl

shevchenko/__init__.py

@@ -0,0 +1,178 @@
+"""shevchenko — Ukrainian declension of names, military ranks, and appointments.
+
+A minimal, dependency-free Python port of shevchenko-js and its military
+extension (https://github.com/tooleks/shevchenko-js, MIT).
+
+    >>> import shevchenko
+    >>> shevchenko.in_genitive(
+    ...     gender="masculine",
+    ...     given_name="Тарас",
+    ...     patronymic_name="Григорович",
+    ...     family_name="Шевченко",
+    ...     military_rank="старший солдат",
+    ... )
+    {'given_name': 'Тараса', 'patronymic_name': 'Григоровича',
+     'family_name': 'Шевченка', 'military_rank': 'старшого солдата'}
+
+When ``gender`` is omitted it is auto-detected from the patronymic or given
+name; an undetectable gender raises :class:`InputValidationError`.
+"""
+
+import unicodedata
+
+from . import _gender, _military, _names
+from ._language import (  # noqa: F401  (re-exported constants)
+    ABLATIVE,
+    ACCUSATIVE,
+    CASES,
+    DATIVE,
+    FEMININE,
+    GENDERS,
+    GENITIVE,
+    LOCATIVE,
+    MASCULINE,
+    NOMINATIVE,
+    VOCATIVE,
+)
+
+__all__ = [
+    "InputValidationError",
+    "detect_gender",
+    "in_case",
+    "in_nominative",
+    "in_genitive",
+    "in_dative",
+    "in_accusative",
+    "in_ablative",
+    "in_locative",
+    "in_vocative",
+    "CASES",
+    "GENDERS",
+    "MASCULINE",
+    "FEMININE",
+    "NOMINATIVE",
+    "GENITIVE",
+    "DATIVE",
+    "ACCUSATIVE",
+    "ABLATIVE",
+    "LOCATIVE",
+    "VOCATIVE",
+]
+
+__version__ = "0.1.0"
+
+
+class InputValidationError(ValueError):
+    pass
+
+
+_NAME_FIELDS = ("given_name", "patronymic_name", "family_name")
+_FIELDS = _NAME_FIELDS + ("military_rank", "military_appointment")
+
+_INFLECTORS = {
+    "given_name": _names.inflect_given_name,
+    "patronymic_name": _names.inflect_patronymic_name,
+    "family_name": _names.inflect_family_name,
+}
+
+
+def _normalize_input(source, kwargs, allowed_fields):
+    merged = {**(source or {}), **kwargs}
+    unknown = set(merged) - set(allowed_fields) - {"gender"}
+    if unknown:
+        raise InputValidationError(f"Unknown parameters: {sorted(unknown)}.")
+    normalized = {}
+    for field in allowed_fields:
+        value = merged.get(field)
+        if value is None:
+            continue
+        if not isinstance(value, str):
+            raise InputValidationError(f'The "{field}" parameter must be a string.')
+        normalized[field] = unicodedata.normalize("NFC", value)
+    if not normalized:
+        raise InputValidationError(
+            f"At least one of the following parameters must present: {allowed_fields}."
+        )
+    return merged.get("gender"), normalized
+
+
+def _resolve_gender(gender, fields):
+    if gender in GENDERS:
+        return gender
+    if gender is not None:
+        raise InputValidationError(
+            f'The "gender" parameter must be one of {GENDERS}, got {gender!r}.'
+        )
+    detected = _gender.detect_gender(
+        given_name=fields.get("given_name"),
+        patronymic_name=fields.get("patronymic_name"),
+    )
+    if detected is None:
+        raise InputValidationError(
+            'The grammatical gender could not be detected; pass gender="masculine"'
+            ' or gender="feminine" explicitly.'
+        )
+    return detected
+
+
+def in_case(case, input=None, **kwargs):
+    """Inflect the given fields in ``case`` and return them as a dict.
+
+    Fields: given_name, patronymic_name, family_name, military_rank,
+    military_appointment. ``gender`` applies to the name fields and is
+    auto-detected when omitted.
+    """
+    if case not in CASES:
+        raise InputValidationError(f'The "case" parameter must be one of {CASES}.')
+    gender, fields = _normalize_input(input, kwargs, _FIELDS)
+    if any(field in fields for field in _NAME_FIELDS):
+        gender = _resolve_gender(gender, fields)
+
+    result = {}
+    for field, value in fields.items():
+        if field in _INFLECTORS:
+            result[field] = _INFLECTORS[field](value, gender, case)
+        elif field == "military_rank":
+            result[field] = _military.inflect_military(value, case, _military.RANK)
+        else:
+            result[field] = _military.inflect_military(
+                value, case, _military.APPOINTMENT
+            )
+    return result
+
+
+def in_nominative(input=None, **kwargs):
+    return in_case(NOMINATIVE, input, **kwargs)
+
+
+def in_genitive(input=None, **kwargs):
+    return in_case(GENITIVE, input, **kwargs)
+
+
+def in_dative(input=None, **kwargs):
+    return in_case(DATIVE, input, **kwargs)
+
+
+def in_accusative(input=None, **kwargs):
+    return in_case(ACCUSATIVE, input, **kwargs)
+
+
+def in_ablative(input=None, **kwargs):
+    return in_case(ABLATIVE, input, **kwargs)
+
+
+def in_locative(input=None, **kwargs):
+    return in_case(LOCATIVE, input, **kwargs)
+
+
+def in_vocative(input=None, **kwargs):
+    return in_case(VOCATIVE, input, **kwargs)
+
+
+def detect_gender(input=None, **kwargs):
+    """Return "masculine"/"feminine" from the patronymic or given name, else None."""
+    _, fields = _normalize_input(input, kwargs, _NAME_FIELDS)
+    return _gender.detect_gender(
+        given_name=fields.get("given_name"),
+        patronymic_name=fields.get("patronymic_name"),
+    )

shevchenko/_classifier.py

@@ -0,0 +1,87 @@
+"""Family-name word-class classifier.
+
+Pure-Python inference for the tiny upstream tfjs model
+(Embedding 34x16 -> SimpleRNN 16, relu -> Dense 1, sigmoid), preceded by the
+upstream cache of known-hard family names.
+"""
+
+import json
+import math
+import struct
+from functools import lru_cache
+
+from ._data import read_bytes, read_text
+from ._language import ADJECTIVE, ALPHABET_ENCODING, NOUN
+
+_INPUT_SIZE = 20
+_EMBED_DIM = 16
+_UNITS = 16
+
+
+@lru_cache(maxsize=1)
+def _load_model():
+    raw = read_bytes("classifier-weights.bin")
+    values = struct.unpack(f"<{len(raw) // 4}f", raw)
+
+    def take(count):
+        nonlocal values
+        chunk, values = values[:count], values[count:]
+        return chunk
+
+    def matrix(rows, cols):
+        flat = take(rows * cols)
+        return [flat[row * cols : (row + 1) * cols] for row in range(rows)]
+
+    return {
+        "embeddings": matrix(34, _EMBED_DIM),
+        "kernel": matrix(_EMBED_DIM, _UNITS),
+        "recurrent": matrix(_UNITS, _UNITS),
+        "bias": take(_UNITS),
+        "dense_kernel": matrix(_UNITS, 1),
+        "dense_bias": take(1),
+    }
+
+
+@lru_cache(maxsize=1)
+def _load_known_classes():
+    return json.loads(read_text("family-name-classes.json"))
+
+
+def _encode(word, size=_INPUT_SIZE):
+    letters = word[-size:].lower().rjust(size, "-")
+    return [ALPHABET_ENCODING.get(letter, 0) for letter in letters]
+
+
+def _decode(probability):
+    return NOUN if probability >= 0.5 else ADJECTIVE
+
+
+@lru_cache(maxsize=4096)
+def classify_family_name(family_name):
+    """Return the word class ("noun" or "adjective") of a family name."""
+    known = _load_known_classes().get(family_name.lower())
+    if known is not None:
+        return known
+    return _predict(family_name)
+
+
+def _predict(family_name):
+    model = _load_model()
+    state = [0.0] * _UNITS
+    for index in _encode(family_name):
+        embedded = model["embeddings"][index]
+        state = [
+            max(
+                0.0,
+                sum(embedded[i] * model["kernel"][i][unit] for i in range(_EMBED_DIM))
+                + sum(state[i] * model["recurrent"][i][unit] for i in range(_UNITS))
+                + model["bias"][unit],
+            )
+            for unit in range(_UNITS)
+        ]
+    logit = (
+        sum(state[i] * model["dense_kernel"][i][0] for i in range(_UNITS))
+        + model["dense_bias"][0]
+    )
+    probability = 1.0 / (1.0 + math.exp(-logit))
+    return _decode(probability)

shevchenko/_data.py

@@ -0,0 +1,20 @@
+"""Package data access via plain file paths.
+
+Deliberately avoids importlib.resources: its import chain (inspect, shutil,
+tempfile, ...) costs ~25 ms, dwarfing this whole library. The trade-off is no
+zipimport support, which this package does not need.
+"""
+
+import os
+
+_DIR = os.path.join(os.path.dirname(__file__), "data")
+
+
+def read_text(name):
+    with open(os.path.join(_DIR, name), encoding="utf-8") as file:
+        return file.read()
+
+
+def read_bytes(name):
+    with open(os.path.join(_DIR, name), "rb") as file:
+        return file.read()

shevchenko/_gender.py

@@ -0,0 +1,42 @@
+"""Grammatical gender detection from given-name / patronymic endings."""
+
+import json
+import re
+from functools import lru_cache
+
+from ._data import read_text
+from ._language import FEMININE, MASCULINE
+
+
+@lru_cache(maxsize=None)
+def _load_detector(file_name):
+    rules = json.loads(read_text(file_name))
+    return (
+        re.compile(rules["masculine"], re.IGNORECASE),
+        re.compile(rules["feminine"], re.IGNORECASE),
+    )
+
+
+def _detect(word, file_name):
+    masculine_pattern, feminine_pattern = _load_detector(file_name)
+    masculine_match = masculine_pattern.search(word)
+    feminine_match = feminine_pattern.search(word)
+    if masculine_match and not feminine_match:
+        return MASCULINE
+    if feminine_match and not masculine_match:
+        return FEMININE
+    if masculine_match and feminine_match:
+        # Both endings match: the longer match wins, ties go to feminine.
+        if len(masculine_match.group(0)) > len(feminine_match.group(0)):
+            return MASCULINE
+        return FEMININE
+    return None
+
+
+def detect_gender(given_name=None, patronymic_name=None):
+    """Return "masculine"/"feminine", or None when undetectable."""
+    if patronymic_name:
+        return _detect(patronymic_name.lower(), "patronymic-name-rules.json")
+    if given_name:
+        return _detect(given_name.lower(), "given-name-rules.json")
+    return None

shevchenko/_inflector.py

@@ -0,0 +1,81 @@
+"""Regex-driven word declension engine (port of shevchenko-js word-declension)."""
+
+import json
+import re
+from functools import lru_cache
+
+from ._data import read_text
+from ._language import copy_letter_case
+
+# Python's stdlib `re` rejects variable-width lookbehinds, which two upstream
+# rules use. Both are only ever evaluated as boolean searches, so they can be
+# rewritten into equivalent lookbehind-free / fixed-width forms.
+_PATTERN_REWRITES = {
+    "((?<=[аеєиіїоуюя].*[аеєиіїоуюя].*л)|(?<=[аеєиіїоуюя].*[^л]))ок$": (
+        "([аеєиіїоуюя].*[аеєиіїоуюя].*л|[аеєиіїоуюя].*[^л])ок$"
+    ),
+    "(?<!ус|в|н)ин$": "(?<!ус)(?<!в)(?<!н)ин$",
+}
+
+
+@lru_cache(maxsize=None)
+def _compile(pattern):
+    return re.compile(_PATTERN_REWRITES.get(pattern, pattern), re.IGNORECASE)
+
+
+def _load_rules():
+    rules = json.loads(read_text("declension-rules.json"))
+    rules.sort(key=lambda rule: rule["priority"], reverse=True)
+    return rules
+
+
+_RULES = _load_rules()
+
+
+def _apply_rule(rule, word, case):
+    # Cases with no commands are omitted from the data entirely (word unchanged).
+    commands = rule["grammaticalCases"].get(case)
+    if not commands:
+        return word
+    commands_by_group = commands[0]
+    modify = _compile(rule["pattern"]["modify"])
+
+    def replace(match):
+        parts = []
+        for group_index in range(modify.groups):
+            value = match.group(group_index + 1) or ""
+            command = commands_by_group.get(str(group_index))
+            if command is not None:
+                if command["action"] == "replace":
+                    value = command["value"]
+                else:  # append
+                    value += command["value"]
+            parts.append(value)
+        return "".join(parts)
+
+    return copy_letter_case(word, modify.sub(replace, word))
+
+
+def inflect_word(word, case, gender, word_class=None, application_type=None, strict=False):
+    """Inflect a single word, applying the highest-priority matching rule.
+
+    ``application_type`` limits rules to a usage ("givenName", "patronymicName",
+    "familyName"); non-strict matching also admits rules with no usage listed.
+    Returns the word unchanged when no rule matches.
+    """
+    for rule in _RULES:
+        if gender not in rule["gender"]:
+            continue
+        if application_type is not None:
+            applications = rule["applicationType"]
+            if strict:
+                if application_type not in applications:
+                    continue
+            elif applications and application_type not in applications:
+                continue
+        if word_class is not None and rule["wordClass"] != word_class:
+            continue
+        if not _compile(rule["pattern"]["find"]).search(word):
+            continue
+        return _apply_rule(rule, word, case)
+    return word

shevchenko/_language.py

@@ -0,0 +1,53 @@
+"""Ukrainian language primitives shared by the declension modules."""
+
+MASCULINE = "masculine"
+FEMININE = "feminine"
+GENDERS = (MASCULINE, FEMININE)
+
+NOMINATIVE = "nominative"
+GENITIVE = "genitive"
+DATIVE = "dative"
+ACCUSATIVE = "accusative"
+ABLATIVE = "ablative"
+LOCATIVE = "locative"
+VOCATIVE = "vocative"
+CASES = (NOMINATIVE, GENITIVE, DATIVE, ACCUSATIVE, ABLATIVE, LOCATIVE, VOCATIVE)
+
+NOUN = "noun"
+ADJECTIVE = "adjective"
+
+# Letter -> 1-based position in the Ukrainian alphabet; 0 is reserved for
+# padding/unknown characters in the classifier input encoding.
+ALPHABET_ENCODING = {
+    letter: index
+    for index, letter in enumerate("абвгґдеєжзиіїйклмнопрстуфхцчшщьюя", start=1)
+}
+
+_VOWELS = set("аоуеиіяюєїАОУЕИІЯЮЄЇ")
+
+
+def is_monosyllable(word):
+    return sum(letter in _VOWELS for letter in word) == 1
+
+
+def copy_letter_case(template_word, target_word):
+    """Reapply the letter-case pattern of ``template_word`` onto ``target_word``.
+
+    When the target is longer than the template, the case of the template's
+    last letter is extended over the remainder.
+    """
+    result = []
+    for index, target_letter in enumerate(target_word):
+        if index < len(template_word):
+            template_letter = template_word[index]
+        elif template_word:
+            template_letter = template_word[-1]
+        else:
+            template_letter = ""
+        if template_letter == template_letter.lower():
+            result.append(target_letter.lower())
+        elif template_letter == template_letter.upper():
+            result.append(target_letter.upper())
+        else:
+            result.append(target_letter)
+    return "".join(result)

shevchenko/_military.py

@@ -0,0 +1,64 @@
+"""Inflection of military ranks and appointments (port of shevchenko-ext-military)."""
+
+import json
+import re
+from functools import lru_cache
+
+from ._data import read_text
+from ._inflector import inflect_word
+
+RANK = "militaryRank"
+APPOINTMENT = "militaryAppointment"
+
+_DELIMITERS_START = re.compile(r'^["\'()]+')
+_DELIMITERS_END = re.compile(r'["\'()]+$')
+
+
+@lru_cache(maxsize=None)
+def _load_json(file_name):
+    return json.loads(read_text(file_name))
+
+
+def _matches_all(patterns, word):
+    return all(re.search(pattern, word, re.IGNORECASE) for pattern in patterns)
+
+
+def _inflect_single_word(word, case):
+    core = word
+    start_match = _DELIMITERS_START.search(core)
+    start = start_match.group(0) if start_match else ""
+    core = core[len(start):]
+    end_match = _DELIMITERS_END.search(core)
+    end = end_match.group(0) if end_match else ""
+    core = core[: len(core) - len(end)] if end else core
+
+    for rule in _load_json("military-word-classes.json"):
+        if _matches_all(rule["include"], core):
+            inflected = inflect_word(
+                core, case, rule["gender"], word_class=rule["wordClass"]
+            )
+            return start + inflected + end
+    return word
+
+
+def inflect_military(text, case, use_case):
+    """Inflect a military rank or appointment phrase word by word.
+
+    Words not recognized by the classifier rules (proper names, abbreviations,
+    already-genitive qualifiers) are left unchanged.
+    """
+    hyphenation_rules = _load_json("military-hyphenation.json")
+    result = []
+    for word in text.split(" "):
+        hyphenated = any(
+            (rule.get("useCase") is None or rule["useCase"] == use_case)
+            and _matches_all(rule["include"], word)
+            for rule in hyphenation_rules
+        )
+        if hyphenated:
+            result.append(
+                "-".join(_inflect_single_word(part, case) for part in word.split("-"))
+            )
+        else:
+            result.append(_inflect_single_word(word, case))
+    return " ".join(result)

shevchenko/_names.py

@@ -0,0 +1,58 @@
+"""Inflection of given names, patronymics, and family names."""
+
+import re
+
+from ._classifier import classify_family_name
+from ._inflector import inflect_word
+from ._language import FEMININE, MASCULINE, is_monosyllable
+
+# Endings for which a family name may be either a noun or an adjective, so the
+# classifier must disambiguate before rules are applied.
+_UNCERTAIN_FEMININE = re.compile("[ая]$", re.IGNORECASE)
+_UNCERTAIN_MASCULINE = re.compile("(ой|ий|ій|их)$", re.IGNORECASE)
+
+
+def _inflect_parts(name, inflect_part):
+    parts = name.split("-")
+    last_index = len(parts) - 1
+    return "-".join(
+        inflect_part(part, index == last_index) for index, part in enumerate(parts)
+    )
+
+
+def inflect_given_name(name, gender, case):
+    return _inflect_parts(
+        name,
+        lambda part, _: inflect_word(part, case, gender, application_type="givenName"),
+    )
+
+
+def inflect_patronymic_name(name, gender, case):
+    return _inflect_parts(
+        name,
+        lambda part, _: inflect_word(
+            part, case, gender, application_type="patronymicName", strict=True
+        ),
+    )
+
+
+def _is_uncertain_family_name(part, gender):
+    if gender == FEMININE:
+        return bool(_UNCERTAIN_FEMININE.search(part))
+    if gender == MASCULINE:
+        return bool(_UNCERTAIN_MASCULINE.search(part))
+    return False
+
+
+def inflect_family_name(name, gender, case):
+    def inflect_part(part, is_last):
+        if not is_last and is_monosyllable(part):
+            return part
+        word_class = None
+        if _is_uncertain_family_name(part, gender):
+            word_class = classify_family_name(part)
+        return inflect_word(
+            part, case, gender, word_class=word_class, application_type="familyName"
+        )
+
+    return _inflect_parts(name, inflect_part)