clafrica 1.0.1

Clafrica keyboard mapping for Nufi (Fe'éfě'e): converts ASCII shortcut sequences to Unicode characters

clafrica

Python library for the Clafrica keyboard input method — converts ASCII shortcut sequences into Nufi (Fe'éfě'e) Unicode characters.

Install

pip install clafrica

---

Quick start

from clafrica import apply_mapping, finalize_input

apply_mapping("af1 e2 n*")   # → "ɑ̀ é ŋ"
apply_mapping("eu3 af5")     # → "ə̄ ɑ̂"
finalize_input("eu3")        # → "ə̄"

---

API

apply_mapping(text)

Converts all Clafrica shortcuts in text to Unicode, preserving whitespace.

from clafrica import apply_mapping

apply_mapping("af1 e2 n*")   # → "ɑ̀ é ŋ"
apply_mapping("uu1 o*2")     # → "ʉ̀ ɔ́"
apply_mapping("N* O*")       # → "Ŋ Ɔ"
apply_mapping("eu3 af5")     # → "ə̄ ɑ̂"

Live-typing mode — pass preserve_ambiguous_trailing=True to leave the last token untouched while the user may still extend it:

apply_mapping("af", preserve_ambiguous_trailing=True)  # → "af"  (could become af1, af2…)
apply_mapping("af1")                                   # → "ɑ̀"

finalize_input(text)

Like apply_mapping but also resolves any trailing ambiguous shortcut — use this when the user confirms input (e.g. presses Enter or Space).

from clafrica import finalize_input

finalize_input("eu3")   # → "ə̄"
finalize_input("af1")   # → "ɑ̀"
finalize_input("n*")    # → "ŋ"

ClafricaEngine — advanced use

Instantiate the engine directly for a custom mapping or extra entries.

from clafrica import ClafricaEngine

# Add project-specific shortcuts on top of the default table
engine = ClafricaEngine(extra={"nkap": "ŋkɑ̄p"})
engine.apply_mapping("nkap e2")   # → "ŋkɑ̄p é"
engine.finalize_input("eu3")      # → "ə̄"
engine.lookup("af1")              # → "ɑ̀"
engine.lookup("xyz")              # → None

# Fully custom table (replaces the default)
engine = ClafricaEngine(mapping={"a1": "à", "e1": "è"})

---

Shortcut reference

Shortcut	Output	Notes
af	ɑ	open-a
eu	ə	schwa
ai	ε	epsilon
o*	ɔ	open-o
uu	ʉ	u-bar
u-	ʉ	u-bar (alternative)
n*	ŋ	eng
N*	Ŋ	Eng (uppercase)
b*	ɓ	implosive b
d*	ɗ	implosive d
*n	ɲ	palatal n
a1 a2 a3	à á ā	low / mid / high tone
a5 a7	â ǎ	rising / falling tone
af1 af2 af3	ɑ̀ ɑ́ ɑ̄	open-a tones
eu1 eu2 eu3	ə̀ ə́ ə̄	schwa tones
ai1 ai2 ai3	ɛ̀ έ ɛ̄	epsilon tones
o*1 o*2 o*3	ɔ̀ ɔ́ ɔ̄	open-o tones
uu1 uu2 uu3	ʉ̀ ʉ́ ʉ̄	u-bar tones

Tone digits: 1 = low, 2 = mid, 3 = high, 5 = rising, 7 = falling.

Phrase shortcuts (space-terminated)

These require a trailing space to trigger:

Type	Output
af	ɑ
eu	ə
ai	ε
uu	ʉ

---

Notes

• ASCII-only shortcuts are matched case-insensitively (AF1 = af1).
• Unicode shortcuts (e.g. à2, ɑ́1) are case-sensitive.
• The mapping table is the canonical one used by the Nufi Android and Windows keyboards.

---

License

MIT