serbian-translit 0.4.2__tar.gz

serbian_translit-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apakabarlabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

serbian_translit-0.4.2/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: serbian-translit
+Version: 0.4.2
+Summary: Deterministic Serbian and Montenegrin script conversion (Cyrillic ↔ Latin).
+Author: Apakabarlabs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/apakabarlabs/serbian-translit-python
+Project-URL: Documentation, https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html
+Project-URL: Changelog, https://github.com/apakabarlabs/serbian-translit-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/apakabarlabs/serbian-translit-python/issues
+Keywords: serbian,montenegrin,transliteration,script,conversion,cyrillic,latin,bcms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Serbian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Requires-Dist: pdoc>=16.0; extra == "dev"
+Dynamic: license-file
+
+[![Tests](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/tests.yml/badge.svg)](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/tests.yml)
+[![Documentation](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/documentation.yml/badge.svg)](https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html)
+
+# serbian-translit
+
+Deterministic Serbian and Montenegrin script conversion, Cyrillic ↔ Latin. Case preservation, digraph handling, quoted-region protection, Roman-numeral and non-native-word filtering.
+
+Both official scripts of Serbian (and Montenegrin) map one-to-one at the letter level: `љ↔lj`, `њ↔nj`, `џ↔dž`, plus `с́↔ś`, `з́↔ź` for Montenegrin. The library plays the pairing from a YAML table; there is no per-language code path in the engine.
+
+## Installation
+
+Install the released package from PyPI:
+
+```bash
+pip install serbian-translit
+```
+
+## Usage
+
+```python
+from serbian_translit import srp, cnr
+
+srp.to_cyr("Njujork")           # 'Њујорк'
+srp.to_cyr("LJUBAV")            # 'ЉУБАВ'
+srp.to_cyr("New York")          # 'New York' (word skipped, has non-native letters)
+srp.to_cyr('grupa „AC/DC"')     # 'група „AC/DC"' (quoted region preserved)
+srp.to_lat("Њујорк")            # 'Njujork'
+
+cnr.to_cyr("śever")             # 'с́евер' (с + U+0301)
+cnr.to_lat("с́евер")             # 'śever'
+```
+
+## Behaviour
+
+- **Digraphs** `lj`, `nj`, `dž` (Latin) ↔ `љ`, `њ`, `џ` (Cyrillic) with case preservation (`Nj` in title-case position, `NJ` inside all-caps).
+- **Montenegrin extras** `ś`, `ź` ↔ `с́`, `з́` (base letter + combining acute U+0301; no precomposed codepoints exist).
+- **Đ variants** `Đ` (U+0110), `đ` (U+0111), `Ð` (U+00D0 Eth), `ð` (U+00F0 eth) all map to `Ђ`/`ђ`.
+- **Roman numerals** (`II`, `XIV`, `XX`) stay in Latin regardless of direction.
+- **Words with non-native letters** (Latin `w`, `x`, `y`, `q`) are skipped whole; treated as foreign inclusions.
+- **Quoted regions** (`"…"`, `„…"`, `“…”`, `«…»`) are preserved verbatim so brand names and foreign quotes survive round-trip.
+- **Non-alphabetic content** (numbers, punctuation, whitespace) is left unchanged.
+
+## Rules and tests
+
+Rules live in [`serbian_translit/data/rules.yaml`](serbian_translit/data/rules.yaml); test cases in [`tests/tests.yaml`](tests/tests.yaml). Both files are the source of truth shared with the [Swift](https://github.com/apakabarlabs/serbian-translit-swift) and (upcoming) Kotlin ports so behaviour stays identical across languages.
+
+## Documentation
+
+The [API reference](https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html) is generated from the public Python API and deployed by GitHub Actions.
+
+## Lines of Code
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/loc-history-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/loc-history-light.svg">
+  <img alt="Lines of Code graph" src=".github/loc-history-light.svg">
+</picture>

serbian_translit-0.4.2/README.md

@@ -0,0 +1,57 @@
+[![Tests](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/tests.yml/badge.svg)](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/tests.yml)
+[![Documentation](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/documentation.yml/badge.svg)](https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html)
+
+# serbian-translit
+
+Deterministic Serbian and Montenegrin script conversion, Cyrillic ↔ Latin. Case preservation, digraph handling, quoted-region protection, Roman-numeral and non-native-word filtering.
+
+Both official scripts of Serbian (and Montenegrin) map one-to-one at the letter level: `љ↔lj`, `њ↔nj`, `џ↔dž`, plus `с́↔ś`, `з́↔ź` for Montenegrin. The library plays the pairing from a YAML table; there is no per-language code path in the engine.
+
+## Installation
+
+Install the released package from PyPI:
+
+```bash
+pip install serbian-translit
+```
+
+## Usage
+
+```python
+from serbian_translit import srp, cnr
+
+srp.to_cyr("Njujork")           # 'Њујорк'
+srp.to_cyr("LJUBAV")            # 'ЉУБАВ'
+srp.to_cyr("New York")          # 'New York' (word skipped, has non-native letters)
+srp.to_cyr('grupa „AC/DC"')     # 'група „AC/DC"' (quoted region preserved)
+srp.to_lat("Њујорк")            # 'Njujork'
+
+cnr.to_cyr("śever")             # 'с́евер' (с + U+0301)
+cnr.to_lat("с́евер")             # 'śever'
+```
+
+## Behaviour
+
+- **Digraphs** `lj`, `nj`, `dž` (Latin) ↔ `љ`, `њ`, `џ` (Cyrillic) with case preservation (`Nj` in title-case position, `NJ` inside all-caps).
+- **Montenegrin extras** `ś`, `ź` ↔ `с́`, `з́` (base letter + combining acute U+0301; no precomposed codepoints exist).
+- **Đ variants** `Đ` (U+0110), `đ` (U+0111), `Ð` (U+00D0 Eth), `ð` (U+00F0 eth) all map to `Ђ`/`ђ`.
+- **Roman numerals** (`II`, `XIV`, `XX`) stay in Latin regardless of direction.
+- **Words with non-native letters** (Latin `w`, `x`, `y`, `q`) are skipped whole; treated as foreign inclusions.
+- **Quoted regions** (`"…"`, `„…"`, `“…”`, `«…»`) are preserved verbatim so brand names and foreign quotes survive round-trip.
+- **Non-alphabetic content** (numbers, punctuation, whitespace) is left unchanged.
+
+## Rules and tests
+
+Rules live in [`serbian_translit/data/rules.yaml`](serbian_translit/data/rules.yaml); test cases in [`tests/tests.yaml`](tests/tests.yaml). Both files are the source of truth shared with the [Swift](https://github.com/apakabarlabs/serbian-translit-swift) and (upcoming) Kotlin ports so behaviour stays identical across languages.
+
+## Documentation
+
+The [API reference](https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html) is generated from the public Python API and deployed by GitHub Actions.
+
+## Lines of Code
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/loc-history-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/loc-history-light.svg">
+  <img alt="Lines of Code graph" src=".github/loc-history-light.svg">
+</picture>

serbian_translit-0.4.2/pyproject.toml

@@ -0,0 +1,150 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serbian-translit"
+dynamic = ["version"]
+description = "Deterministic Serbian and Montenegrin script conversion (Cyrillic ↔ Latin)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Apakabarlabs" }]
+keywords = ["serbian", "montenegrin", "transliteration", "script", "conversion", "cyrillic", "latin", "bcms"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: Serbian",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = ["PyYAML>=6.0"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "types-PyYAML>=6.0",
+    "build>=1.0",
+    "twine>=6.0",
+    "pdoc>=16.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/apakabarlabs/serbian-translit-python"
+Documentation = "https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html"
+Changelog = "https://github.com/apakabarlabs/serbian-translit-python/blob/main/CHANGELOG.md"
+Issues = "https://github.com/apakabarlabs/serbian-translit-python/issues"
+
+[tool.setuptools.packages.find]
+include = ["serbian_translit*"]
+
+[tool.setuptools.package-data]
+serbian_translit = ["data/rules.yaml"]
+
+# Single source of truth for the version. `__init__.py.__version__` is
+# resolved at build time by setuptools; runtime code reads the same
+# constant directly.
+[tool.setuptools.dynamic]
+version = { attr = "serbian_translit.__version__" }
+
+[tool.ruff]
+line-length = 120
+# Match the lowest supported runtime (requires-python above). Bumping
+# either without the other splits ruff's UP autofixes from the versions
+# users actually run.
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "B",    # flake8-bugbear
+    "A",    # flake8-builtins (don't shadow builtins)
+    "C4",   # flake8-comprehensions
+    "COM",  # flake8-commas
+    "ISC",  # flake8-implicit-str-concat
+    "PIE",  # flake8-pie (misc bad patterns)
+    "PT",   # flake8-pytest-style
+    "Q",    # flake8-quotes
+    "RET",  # flake8-return
+    "SIM",  # flake8-simplify
+    "TID",  # flake8-tidy-imports
+    "ARG",  # flake8-unused-arguments
+    "PTH",  # flake8-use-pathlib
+    "ERA",  # flake8-eradicate (dead commented code)
+    "PL",   # pylint
+    "TRY",  # tryceratops (try/except best practices)
+    "PERF", # perflint
+    "FURB", # refurb (modern-Python rewrites)
+    "RUF",  # ruff-specific
+    "UP",   # pyupgrade
+    "S",    # flake8-bandit (security)
+]
+ignore = [
+    "E501",    # line too long, handled by formatter
+    "B008",    # function calls in argument defaults
+    "COM812",  # trailing comma missing, conflicts with formatter
+    "ISC001",  # implicit-string-concat, conflicts with formatter
+    "TRY003",  # long messages inside exception class, fine here
+    # This library exists to distinguish Cyrillic vs Latin lookalikes.
+    # `с` vs `c` in a comment is the whole point; ruff's ambiguous-char
+    # warnings would fire on every meaningful docstring.
+    "RUF001",  # ambiguous unicode in string
+    "RUF002",  # ambiguous unicode in docstring
+    "RUF003",  # ambiguous unicode in comment
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]  # pytest tests are all assert
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+files = ["serbian_translit", "tests"]
+
+[[tool.mypy.overrides]]
+module = ["yaml"]
+ignore_missing_imports = true
+
+[tool.coverage.run]
+source = ["serbian_translit"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

serbian_translit-0.4.2/serbian_translit/__init__.py

@@ -0,0 +1,4 @@
+from . import cnr, srp
+
+__version__ = "0.4.2"
+__all__ = ["cnr", "srp"]

serbian_translit-0.4.2/serbian_translit/case.py

@@ -0,0 +1,34 @@
+"""Word-level case detection and reapplication."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CasePattern(Enum):
+    LOWER = "lower"
+    UPPER = "upper"
+    TITLE = "title"
+    MIXED = "mixed"
+
+
+def detect(text: str) -> CasePattern:
+    if text.islower():
+        return CasePattern.LOWER
+    if text.isupper():
+        return CasePattern.UPPER
+    if len(text) > 1 and text[0].isupper() and text[1:].islower():
+        return CasePattern.TITLE
+    return CasePattern.MIXED
+
+
+def apply(text: str, pattern: CasePattern) -> str:
+    match pattern:
+        case CasePattern.LOWER:
+            return text.lower()
+        case CasePattern.UPPER:
+            return text.upper()
+        case CasePattern.TITLE:
+            return text[0].upper() + text[1:].lower()
+        case CasePattern.MIXED:
+            return text

serbian_translit-0.4.2/serbian_translit/cnr.py

@@ -0,0 +1,15 @@
+"""Montenegrin (`cnr`) script conversion, Cyrillic ↔ Latin."""
+
+from __future__ import annotations
+
+from .table import CNR_CYR_TO_LAT, CNR_LAT_TO_CYR
+
+
+def to_cyr(text: str) -> str:
+    """Montenegrin Latin → Cyrillic."""
+    return CNR_LAT_TO_CYR.apply(text)
+
+
+def to_lat(text: str) -> str:
+    """Montenegrin Cyrillic → Latin."""
+    return CNR_CYR_TO_LAT.apply(text)

serbian_translit-0.4.2/serbian_translit/data/rules.yaml

@@ -0,0 +1,185 @@
+# Serbian/Montenegrin script conversion rules.
+#
+# Each rule declares a source→target script and gives three ordered maps:
+#   digraphs: matched first, greedy (`lj`→`љ`, `dž`→`џ`); case-aware.
+#   pre_char: pre-processed single-character remaps applied before `singles`.
+#                Used for accepting alternate codepoints (Đ variants) that
+#                collapse to the same base letter.
+#   singles:  1:1 base-letter map.
+# Case handling: the engine looks at the surrounding word to decide
+# LOWER / UPPER / TITLE, so `Nj` in "Njujork" but `NJ` in "NJUJORK".
+#
+# extras_in_word: letters (beyond base ASCII / Cyrillic ranges) that count
+# as part of a word for tokenisation. Without listing them, `š` or `ž` would
+# split a Latin word into pieces and case-detection would misfire.
+#
+# non_native_letters: if a word contains any of these letters, it is left
+# untouched (foreign inclusion). Applies to Latin source only.
+
+rules:
+
+  - source: srp-latn
+    target: srp-cyrl
+    digraphs:
+      lj: љ
+      nj: њ
+      dž: џ
+    pre_char:
+      "Ð": "Đ"   # Ð (Eth) → Đ (D-stroke): editors often type Eth by accident
+      "ð": "đ"   # ð (eth) → đ (d-stroke): same
+    singles:
+      a: а
+      b: б
+      c: ц
+      "č": ч
+      "ć": ћ
+      d: д
+      "đ": ђ
+      e: е
+      f: ф
+      g: г
+      h: х
+      i: и
+      j: ј
+      k: к
+      l: л
+      m: м
+      n: н
+      o: о
+      p: п
+      r: р
+      s: с
+      "š": ш
+      t: т
+      u: у
+      v: в
+      z: з
+      "ž": ж
+    extras_in_word: "čČćĆđĐšŠžŽ"
+    non_native_letters: "wxyqWXYQ"
+    # Words that look like Roman numerals but are Serbian
+    # pronouns/particles, compared case-insensitively.
+    never_roman: ["MI", "LI", "VI", "CI"]
+
+  - source: srp-cyrl
+    target: srp-latn
+    digraphs:
+      "љ": lj
+      "њ": nj
+      "џ": dž
+    singles:
+      "а": a
+      "б": b
+      "в": v
+      "г": g
+      "д": d
+      "ђ": "đ"
+      "е": e
+      "ж": "ž"
+      "з": z
+      "и": i
+      "ј": j
+      "к": k
+      "л": l
+      "м": m
+      "н": n
+      "о": o
+      "п": p
+      "р": r
+      "с": s
+      "т": t
+      "ћ": "ć"
+      "у": u
+      "ф": f
+      "х": h
+      "ц": c
+      "ч": "č"
+      "ш": "š"
+    extras_in_word: ""
+    non_native_letters: ""
+
+  - source: cnr-latn
+    target: cnr-cyrl
+    digraphs:
+      lj: љ
+      nj: њ
+      dž: џ
+    pre_char:
+      "Ð": "Đ"
+      "ð": "đ"
+    singles:
+      a: а
+      b: б
+      c: ц
+      "č": ч
+      "ć": ћ
+      d: д
+      "đ": ђ
+      e: е
+      f: ф
+      g: г
+      h: х
+      i: и
+      j: ј
+      k: к
+      l: л
+      m: м
+      n: н
+      o: о
+      p: п
+      r: р
+      s: с
+      "ś": "с́"
+      "š": ш
+      t: т
+      u: у
+      v: в
+      z: з
+      "ź": "з́"
+      "ž": ж
+    extras_in_word: "čČćĆđĐšŠžŽśŚźŹ"
+    non_native_letters: "wxyqWXYQ"
+    # Words that look like Roman numerals but are Montenegrin
+    # pronouns/particles, compared case-insensitively.
+    never_roman: ["MI", "LI", "VI", "CI"]
+
+  - source: cnr-cyrl
+    target: cnr-latn
+    digraphs:
+      "љ": lj
+      "њ": nj
+      "џ": dž
+      # с́ / з́ are two codepoints (base + U+0301). Handled as digraphs so the
+      # combining mark is consumed with its base letter and does not leak.
+      "с́": "ś"
+      "з́": "ź"
+    singles:
+      "а": a
+      "б": b
+      "в": v
+      "г": g
+      "д": d
+      "ђ": "đ"
+      "е": e
+      "ж": "ž"
+      "з": z
+      "и": i
+      "ј": j
+      "к": k
+      "л": l
+      "м": m
+      "н": n
+      "о": o
+      "п": p
+      "р": r
+      "с": s
+      "т": t
+      "ћ": "ć"
+      "у": u
+      "ф": f
+      "х": h
+      "ц": c
+      "ч": "č"
+      "ш": "š"
+    extras_in_word: "́"
+    non_native_letters: ""

serbian_translit-0.4.2/serbian_translit/letters.py

@@ -0,0 +1,34 @@
+"""Char-by-char letter map, digraph-first."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_DIGRAPH_WIDTH = 2
+_SINGLE_WIDTH = 1
+_LOOKUP_WIDTHS = (_DIGRAPH_WIDTH, _SINGLE_WIDTH)
+
+
+@dataclass(frozen=True)
+class LetterMap:
+    digraphs: dict[str, str]
+    singles: dict[str, str]
+
+    def convert(self, lowered: str) -> str:
+        result: list[str] = []
+        i = 0
+        while i < len(lowered):
+            replacement, width = self._match_at(lowered, i)
+            result.append(replacement)
+            i += width
+        return "".join(result)
+
+    def _match_at(self, lowered: str, i: int) -> tuple[str, int]:
+        for width in _LOOKUP_WIDTHS:
+            if i + width > len(lowered):
+                continue
+            candidate = lowered[i : i + width]
+            if candidate in self.digraphs:
+                return self.digraphs[candidate], width
+        ch = lowered[i]
+        return self.singles.get(ch, ch), _SINGLE_WIDTH

serbian_translit-0.4.2/serbian_translit/protection.py

@@ -0,0 +1,45 @@
+"""Stash paired quotes and URL/email/handle tokens so they round-trip untouched."""
+
+from __future__ import annotations
+
+import re
+import uuid
+
+_QUOTED_RE = re.compile(
+    r"„[^„”“]*?[”“\"]"
+    r"|«[^«»]*?»"
+    r"|“[^“”]*?”"
+    r"|\"[^\"]*?\"",
+    re.DOTALL,
+)
+
+_STOP = r"\s<>"
+_TOKEN_RE = re.compile(
+    rf"[a-zA-Z][a-zA-Z0-9+.\-]*://[^{_STOP}]+"
+    rf"|www\.[^{_STOP}]+"
+    rf"|[^{_STOP}@]+@[^{_STOP}@]+\.[^{_STOP}@]+"
+    rf"|#[^{_STOP}#@]+"
+    rf"|@[^{_STOP}#@]+",
+)
+
+
+class ProtectedRegions:
+    def __init__(self) -> None:
+        self._slots: dict[str, str] = {}
+        self._counter = 0
+        self._prefix = uuid.uuid4().hex
+
+    def stash_all(self, text: str) -> str:
+        text = _TOKEN_RE.sub(self._stash, text)
+        return _QUOTED_RE.sub(self._stash, text)
+
+    def restore(self, text: str) -> str:
+        for key, original in self._slots.items():
+            text = text.replace(key, original)
+        return text
+
+    def _stash(self, match: re.Match[str]) -> str:
+        key = f"\x00Q_{self._prefix}_{self._counter}\x00"
+        self._slots[key] = match.group(0)
+        self._counter += 1
+        return key

serbian_translit-0.4.2/serbian_translit/roman.py

@@ -0,0 +1,13 @@
+"""Roman-numeral detection for the transliteration passthrough."""
+
+from __future__ import annotations
+
+import re
+
+_CANONICAL = re.compile(r"^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$")
+
+_MIN_NUMERAL_LEN = 2
+
+
+def is_numeral(word: str) -> bool:
+    return len(word) >= _MIN_NUMERAL_LEN and bool(_CANONICAL.match(word))

serbian_translit-0.4.2/serbian_translit/rule.py

@@ -0,0 +1,71 @@
+"""One source→target script mapping, loaded from ``data/rules.yaml``."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import TypedDict
+
+from . import case
+from .letters import LetterMap
+from .protection import ProtectedRegions
+from .skip import SkipPolicy
+
+_MIXED_CASE_CUTOFF = 2
+
+
+class RuleData(TypedDict, total=False):
+    source: str
+    target: str
+    digraphs: dict[str, str]
+    pre_char: dict[str, str]
+    singles: dict[str, str]
+    extras_in_word: str
+    non_native_letters: str
+    never_roman: list[str]
+
+
+class Rule:
+    def __init__(self, data: RuleData) -> None:
+        self.letters = LetterMap(
+            digraphs={k.lower(): v for k, v in data.get("digraphs", {}).items()},
+            singles=data.get("singles") or {},
+        )
+        self.skip = SkipPolicy(
+            non_native_letters=set(data.get("non_native_letters") or ""),
+            never_roman={w.upper() for w in data.get("never_roman") or []},
+        )
+        self.pre_char: dict[str, str] = data.get("pre_char") or {}
+        extras = data.get("extras_in_word") or ""
+        self.word_split_re = re.compile(rf"(\s+|[^\w{re.escape(extras)}]+)")
+
+    def apply(self, text: str) -> str:
+        text = unicodedata.normalize("NFC", text)
+
+        protection = ProtectedRegions()
+        protected = protection.stash_all(text)
+
+        rendered = "".join(self._convert_part(p) for p in self.word_split_re.split(protected) if p)
+        return protection.restore(rendered)
+
+    def _convert_part(self, part: str) -> str:
+        if any(ch.isalpha() for ch in part):
+            return self._convert_word(part)
+        return part
+
+    def _convert_word(self, word: str) -> str:
+        if self.skip.is_foreign(word) or self.skip.is_roman_numeral(word):
+            return word
+
+        word = self._normalise_pre_char(word)
+
+        pattern = case.detect(word)
+        if pattern is case.CasePattern.MIXED and len(word) > _MIXED_CASE_CUTOFF:
+            return word
+
+        return case.apply(self.letters.convert(word.lower()), pattern)
+
+    def _normalise_pre_char(self, word: str) -> str:
+        if not self.pre_char:
+            return word
+        return "".join(self.pre_char.get(ch, ch) for ch in word)

serbian_translit-0.4.2/serbian_translit/skip.py

@@ -0,0 +1,19 @@
+"""Word-level policies that pass a token through unchanged."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import roman
+
+
+@dataclass(frozen=True)
+class SkipPolicy:
+    non_native_letters: set[str]
+    never_roman: set[str]
+
+    def is_foreign(self, word: str) -> bool:
+        return bool(self.non_native_letters and self.non_native_letters.intersection(word))
+
+    def is_roman_numeral(self, word: str) -> bool:
+        return roman.is_numeral(word) and word.upper() not in self.never_roman

serbian_translit-0.4.2/serbian_translit/srp.py

@@ -0,0 +1,15 @@
+"""Serbian (`srp`) script conversion, Cyrillic ↔ Latin."""
+
+from __future__ import annotations
+
+from .table import SRP_CYR_TO_LAT, SRP_LAT_TO_CYR
+
+
+def to_cyr(text: str) -> str:
+    """Serbian Latin → Cyrillic."""
+    return SRP_LAT_TO_CYR.apply(text)
+
+
+def to_lat(text: str) -> str:
+    """Serbian Cyrillic → Latin."""
+    return SRP_CYR_TO_LAT.apply(text)

serbian_translit-0.4.2/serbian_translit/table.py

@@ -0,0 +1,29 @@
+"""YAML-driven table of ready-built rules, one per source→target pair."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+import yaml
+
+from .rule import Rule, RuleData
+
+
+class _RulesFile(TypedDict):
+    rules: list[RuleData]
+
+
+def _load() -> dict[tuple[str, str], Rule]:
+    path = Path(__file__).parent / "data" / "rules.yaml"
+    with path.open(encoding="utf-8") as f:
+        data: _RulesFile = yaml.safe_load(f)
+    return {(entry["source"], entry["target"]): Rule(entry) for entry in data["rules"]}
+
+
+_TABLE = _load()
+
+SRP_LAT_TO_CYR = _TABLE["srp-latn", "srp-cyrl"]
+SRP_CYR_TO_LAT = _TABLE["srp-cyrl", "srp-latn"]
+CNR_LAT_TO_CYR = _TABLE["cnr-latn", "cnr-cyrl"]
+CNR_CYR_TO_LAT = _TABLE["cnr-cyrl", "cnr-latn"]

serbian_translit-0.4.2/serbian_translit.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: serbian-translit
+Version: 0.4.2
+Summary: Deterministic Serbian and Montenegrin script conversion (Cyrillic ↔ Latin).
+Author: Apakabarlabs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/apakabarlabs/serbian-translit-python
+Project-URL: Documentation, https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html
+Project-URL: Changelog, https://github.com/apakabarlabs/serbian-translit-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/apakabarlabs/serbian-translit-python/issues
+Keywords: serbian,montenegrin,transliteration,script,conversion,cyrillic,latin,bcms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Serbian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Requires-Dist: pdoc>=16.0; extra == "dev"
+Dynamic: license-file
+
+[![Tests](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/tests.yml/badge.svg)](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/tests.yml)
+[![Documentation](https://github.com/apakabarlabs/serbian-translit-python/actions/workflows/documentation.yml/badge.svg)](https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html)
+
+# serbian-translit
+
+Deterministic Serbian and Montenegrin script conversion, Cyrillic ↔ Latin. Case preservation, digraph handling, quoted-region protection, Roman-numeral and non-native-word filtering.
+
+Both official scripts of Serbian (and Montenegrin) map one-to-one at the letter level: `љ↔lj`, `њ↔nj`, `џ↔dž`, plus `с́↔ś`, `з́↔ź` for Montenegrin. The library plays the pairing from a YAML table; there is no per-language code path in the engine.
+
+## Installation
+
+Install the released package from PyPI:
+
+```bash
+pip install serbian-translit
+```
+
+## Usage
+
+```python
+from serbian_translit import srp, cnr
+
+srp.to_cyr("Njujork")           # 'Њујорк'
+srp.to_cyr("LJUBAV")            # 'ЉУБАВ'
+srp.to_cyr("New York")          # 'New York' (word skipped, has non-native letters)
+srp.to_cyr('grupa „AC/DC"')     # 'група „AC/DC"' (quoted region preserved)
+srp.to_lat("Њујорк")            # 'Njujork'
+
+cnr.to_cyr("śever")             # 'с́евер' (с + U+0301)
+cnr.to_lat("с́евер")             # 'śever'
+```
+
+## Behaviour
+
+- **Digraphs** `lj`, `nj`, `dž` (Latin) ↔ `љ`, `њ`, `џ` (Cyrillic) with case preservation (`Nj` in title-case position, `NJ` inside all-caps).
+- **Montenegrin extras** `ś`, `ź` ↔ `с́`, `з́` (base letter + combining acute U+0301; no precomposed codepoints exist).
+- **Đ variants** `Đ` (U+0110), `đ` (U+0111), `Ð` (U+00D0 Eth), `ð` (U+00F0 eth) all map to `Ђ`/`ђ`.
+- **Roman numerals** (`II`, `XIV`, `XX`) stay in Latin regardless of direction.
+- **Words with non-native letters** (Latin `w`, `x`, `y`, `q`) are skipped whole; treated as foreign inclusions.
+- **Quoted regions** (`"…"`, `„…"`, `“…”`, `«…»`) are preserved verbatim so brand names and foreign quotes survive round-trip.
+- **Non-alphabetic content** (numbers, punctuation, whitespace) is left unchanged.
+
+## Rules and tests
+
+Rules live in [`serbian_translit/data/rules.yaml`](serbian_translit/data/rules.yaml); test cases in [`tests/tests.yaml`](tests/tests.yaml). Both files are the source of truth shared with the [Swift](https://github.com/apakabarlabs/serbian-translit-swift) and (upcoming) Kotlin ports so behaviour stays identical across languages.
+
+## Documentation
+
+The [API reference](https://apakabarlabs.github.io/serbian-translit-python/serbian_translit.html) is generated from the public Python API and deployed by GitHub Actions.
+
+## Lines of Code
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/loc-history-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/loc-history-light.svg">
+  <img alt="Lines of Code graph" src=".github/loc-history-light.svg">
+</picture>

serbian_translit-0.4.2/serbian_translit.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+serbian_translit/__init__.py
+serbian_translit/case.py
+serbian_translit/cnr.py
+serbian_translit/letters.py
+serbian_translit/protection.py
+serbian_translit/roman.py
+serbian_translit/rule.py
+serbian_translit/skip.py
+serbian_translit/srp.py
+serbian_translit/table.py
+serbian_translit.egg-info/PKG-INFO
+serbian_translit.egg-info/SOURCES.txt
+serbian_translit.egg-info/dependency_links.txt
+serbian_translit.egg-info/requires.txt
+serbian_translit.egg-info/top_level.txt
+serbian_translit/data/rules.yaml
+tests/test_transliterate.py

serbian_translit-0.4.2/serbian_translit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

serbian_translit-0.4.2/serbian_translit.egg-info/requires.txt

@@ -0,0 +1,11 @@
+PyYAML>=6.0
+
+[dev]
+pytest>=8.0
+pytest-cov>=5.0
+ruff>=0.5
+mypy>=1.10
+types-PyYAML>=6.0
+build>=1.0
+twine>=6.0
+pdoc>=16.0

serbian_translit-0.4.2/serbian_translit.egg-info/top_level.txt

@@ -0,0 +1 @@
+serbian_translit

serbian_translit-0.4.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

serbian_translit-0.4.2/tests/test_transliterate.py

@@ -0,0 +1,41 @@
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+import yaml
+
+from serbian_translit import cnr, srp
+
+_ROUTES: dict[tuple[str, str], Callable[[str], str]] = {
+    ("srp-latn", "srp-cyrl"): srp.to_cyr,
+    ("srp-cyrl", "srp-latn"): srp.to_lat,
+    ("cnr-latn", "cnr-cyrl"): cnr.to_cyr,
+    ("cnr-cyrl", "cnr-latn"): cnr.to_lat,
+}
+
+
+def load_test_cases() -> list[tuple[str, str, str, str, str]]:
+    path = Path(__file__).parent / "tests.yaml"
+    with path.open(encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    return [
+        (section["section"], section["source"], section["target"], case["text"], case["want"])
+        for section in data["tests"]
+        for case in section["cases"]
+    ]
+
+
+@pytest.mark.parametrize(("section", "source", "target", "text", "want"), load_test_cases())
+def test_transliterate(section: str, source: str, target: str, text: str, want: str) -> None:
+    func = _ROUTES[(source, target)]
+    result = func(text)
+    assert result == want, f"[{section}] {source} → {target} ('{text}'): got '{result}', want '{want}'"
+
+
+@pytest.mark.parametrize(
+    "func",
+    [srp.to_cyr, srp.to_lat, cnr.to_cyr, cnr.to_lat],
+    ids=["srp.to_cyr", "srp.to_lat", "cnr.to_cyr", "cnr.to_lat"],
+)
+def test_empty_input_returns_empty_string(func: Callable[[str], str]) -> None:
+    assert func("") == ""