Cython Guide

# Install with development dependencies (builds extensions)
pip install -e ".[dev]"

# Or explicitly build extensions
python setup.py build_ext --inplace

# Install libomp for parallel processing
brew install libomp

# Apple Silicon (M1/M2/M3)
# libomp installed to: /opt/homebrew/opt/libomp

# Intel Mac
# libomp installed to: /usr/local/opt/libomp

# OpenMP comes with gcc
sudo apt install build-essential  # Debian/Ubuntu
sudo yum groupinstall "Development Tools"  # RHEL/CentOS

# Build with debug symbols
python setup.py build_ext --inplace --debug

# Remove compiled extensions
find . -name "*.so" -delete
find . -name "*.cpp" -path "*/myspellchecker/*" -delete
find . -name "*.pyc" -delete
rm -rf build/ *.egg-info/

# Rebuild from scratch
python setup.py build_ext --inplace

# normalize.py -- hard import, NO try/except fallback
from myspellchecker.text.normalize_c import (
    remove_zero_width_chars as c_remove_zero_width,
)
from myspellchecker.text.normalize_c import (
    reorder_myanmar_diacritics as c_reorder_diacritics,
)

# edit_distance.py -- try/except with full Python fallback
try:
    from myspellchecker.algorithms.distance import edit_distance_c
    _HAS_CYTHON_EDIT_DISTANCE = True
except ImportError:
    _HAS_CYTHON_EDIT_DISTANCE = False

# Each function checks the flag and falls back to pure Python:
def levenshtein_distance(s1: str, s2: str) -> int:
    if _HAS_CYTHON_EDIT_DISTANCE:
        return edit_distance_c.levenshtein_distance(s1, s2)
    # ... pure Python implementation follows ...

# syllable_rules.py -- try/except with class-level fallback
try:
    from myspellchecker.core.syllable_rules_c import (
        SyllableRuleValidator as _SyllableRuleValidatorCython,
    )
    SyllableRuleValidator = _SyllableRuleValidatorCython
except ImportError:
    SyllableRuleValidator = _SyllableRuleValidatorPython

# Check if Cython extension loaded
try:
    from myspellchecker.text.normalize_c import remove_zero_width_chars
    print("Cython normalize: loaded")
except ImportError:
    print("Cython normalize: not available")
    # NOTE: There is NO Python fallback for normalize. The normalize.py
    # wrapper uses hard imports (Pattern A), so if the Cython extension
    # is not compiled, importing normalize.py will raise ImportError.

from myspellchecker.algorithms.viterbi import _HAS_CYTHON_VITERBI
print(f"Cython viterbi: {_HAS_CYTHON_VITERBI}")

# normalize_c.pxd
cdef str c_remove_zero_width_chars(str text)
cdef bint c_has_myanmar_script(str text)

# batch_processor.pyx (using the declarations)
from myspellchecker.text.normalize_c cimport c_remove_zero_width_chars

def process_batch(list texts):
    cdef str text
    for text in texts:
        # Direct C-level call (no Python overhead)
        text = c_remove_zero_width_chars(text)

# batch_processor.pyx
from cython.parallel import prange

def process_batch_parallel(list texts, int num_threads=4):
    cdef int i, n = len(texts)
    cdef list results = [None] * n

    # Parallel loop with OpenMP
    for i in prange(n, nogil=True, num_threads=num_threads):
        with gil:
            results[i] = process_single(texts[i])

    return results

# distutils: language = c++

from libcpp.string cimport string
from libcpp.vector cimport vector
from libcpp.unordered_map cimport unordered_map

cdef class EditDistanceCalculator:
    cdef unordered_map[string, int] cache

    cdef int calculate(self, string s1, string s2) nogil:
        # C++ implementation with STL
        pass

from myspellchecker.text.normalize import (
    remove_zero_width_chars,
    normalize,
    normalize_for_lookup,
)

clean = remove_zero_width_chars("မြန်\u200bမာ")  # "မြန်မာ"
normalized = normalize("မြန်မာ")
lookup_form = normalize_for_lookup("မြန်မာ")

from myspellchecker.algorithms.distance.edit_distance_c import (
    levenshtein_distance,
    damerau_levenshtein_distance,
    weighted_damerau_levenshtein_distance,
    set_myanmar_substitution_costs,
)

dist = levenshtein_distance("မြန်", "မြမ်")  # 1
dist = damerau_levenshtein_distance("AB", "BA")  # 1 (includes transposition)

from myspellchecker.core.syllable_rules import SyllableRuleValidator

validator = SyllableRuleValidator(strict=True)
is_valid = validator.validate("မြန်")  # True
is_valid = validator.validate("ြမန်")  # False (medial without consonant)

from myspellchecker.data_pipeline.batch_processor import process_batch

results = process_batch(texts, num_threads=4)

from myspellchecker.algorithms.viterbi import ViterbiTagger

tagger = ViterbiTagger()
tags = tagger.tag_sequence(["သူ", "က", "သွား", "တယ်"])
# ["N", "P_SUBJ", "V", "P_SENT"]

# Run tests for Cython modules
pytest tests/test_normalize.py tests/test_edit_distance.py -v

# Run with coverage (tests both Python and Cython paths)
pytest tests/ --cov=myspellchecker --cov-report=html

# test_normalize.py
import pytest
from myspellchecker.text.normalize_c import remove_zero_width_chars

def test_remove_zero_width_basic():
    text = "hello\u200bworld"
    result = remove_zero_width_chars(text)
    assert result == "helloworld"

@pytest.mark.skipif(not CYTHON_AVAILABLE, reason="Cython not compiled")
def test_cython_zero_width_edge_cases():
    from myspellchecker.text.normalize_c import remove_zero_width_chars

    test_cases = [
        ("hello\u200bworld", "helloworld"),   # ZWSP
        ("မြန်မာ\u200b", "မြန်မာ"),          # Trailing ZWSP
        ("", ""),                              # Empty string
    ]
    for text, expected in test_cases:
        assert remove_zero_width_chars(text) == expected

pip install cython>=3.0

brew install libomp

# If build still fails:
export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"
python setup.py build_ext --inplace

python setup.py build_ext --inplace --force

export CXXFLAGS="-std=c++11"
python setup.py build_ext --inplace

# Build with debug symbols and debug with lldb
python setup.py build_ext --inplace --debug
lldb python -c "import myspellchecker"