wiktionary-ipa

A fast, lightweight, standalone Python library to extract, normalize, and verify British English (Received Pronunciation / RP) International Phonetic Alphabet (IPA) transcriptions directly from en.wiktionary.org.

Zero external dependencies — Python standard library only.

Why wiktionary-ipa?

• Dedicated to British English (RP / SSB): Most English phonetic libraries (eng-to-ipa, CMUdict) default strictly to General American and introduce rhotic errors or flaps. wiktionary-ipa enforces strict RP priority and disqualifies Americanisms (GA, US, flaps [ɾ], rhotic vowels [ɚ, ɝ]).
• Live Action API Batching: Queries en.wiktionary.org using batched requests (up to 50 words per HTTP request) with gzip compression and polite rate limiting.
• Zero Cache, Zero Bloat: Always queries the live crowd-sourced truth from Wiktionary without requiring multi-gigabyte XML dump downloads or stale databases.
• Homograph Disambiguation: Correctly resolves noun vs. verb stress pairs (e.g., record N -> /ˈrekɔːd/ vs. record V -> /rɪˈkɔːd/).
• Compound Prosody Synthesis: Automatically constructs natural British English stress patterns for idioms, phrasal verbs, and compounds missing dedicated dictionary entries.
• Phonetic Equivalence Engine: Intelligently matches variant representations (syllabic consonants like ʃn vs. ʃən, linking (r), optional yods (j), and optional plurals).

Installation

pip install wiktionary-ipa

Or install directly from GitHub:

pip install git+https://github.com/thanhqng1510/wiktionary-ipa.git

Quick Python API

import wiktionary_ipa as wipa

# 1. Single Word Lookup (Live Web)
ipa = wipa.lookup("abbreviation")
print(ipa)  # /əˌbriːviˈeɪʃən/

# 2. Batch Lookup (50 titles per HTTP request, gzip-compressed)
results = wipa.batch_lookup(["apple", "banana", "record N", "record V"])
# {
#   "apple": "/ˈæp.əl/",
#   "banana": "/bəˈnɑː.nə/",
#   "record N": "/ˈrekɔːd/",
#   "record V": "/rɪˈkɔːd/"
# }

# 3. Verify Word Against Live Web
res = wipa.verify_word("backward(s)", "/ˈbækwəd(z)/")
print(res["status"])  # 'EQUIVALENT' (matches live /bækwə(r)d/)

# 4. Phonetic Equivalence Check
wipa.phonetically_equivalent("/ˈbækwəd(z)/", "/ˈbækwə(r)d/")  # True
wipa.phonetically_equivalent("/əˈdɪʃn/", "/əˈdɪʃən/")         # True

# 5. Normalizer
wipa.normalize_ipa("[ˈbeɾə]")  # '/ˈbetə/'

Command-Line Interface (CLI)

wiktionary-ipa provides a fast CLI:

# Lookup single word
wiktionary-ipa "abbreviation"
# abbreviation: /əˌbriːviˈeɪʃən/

# Batch lookup
wiktionary-ipa apple banana cucumber

# Verify expected pronunciation against live Wiktionary
wiktionary-ipa --verify "sea bass" "/ˈsiː bæs/"
# Word: sea bass
# Status: MATCH
# Expected: /ˈsiː bæs/
# Live Web: /ˈsiː bæs/

# JSON output for CI automation
wiktionary-ipa --verify "backward(s)" "/ˈbækwəd(z)/" --json

Architecture & Modules

• client.py (WiktionaryClient): Handles MediaWiki Action API communication, batching up to 50 titles, HTTP gzip decompression, polite throttling (0.35s), and exponential backoff on HTTP 429/503.
• dialects.py: Received Pronunciation scoring (+100 for RP/SSB, +90 for UK/British) and hard rejection filters for non-RP accents (US, GA, Canada, Australia, Scotland, Ireland).
• normalizer.py: Cleans IPA formatting, enforces Unicode slashes, standardizes script characters (e.g. ɡ -> g), and evaluates phonetic equivalence.
• parser.py: Extracts English pronunciation sections from raw Wikitext, parses {{IPA|en|...}} templates, filters dialect tags, and resolves POS homographs.
• prosody.py: Synthesizes compound noun stress, phrasal verb nuclear stress, and grammatical weak forms when an exact multi-word Wiktionary entry is absent.

Running Tests

All 22 unit tests execute in ~0.001 seconds using the standard library unittest runner:

python3 -m unittest discover -s tests

License

MIT License. See LICENSE for details.