Metadata-Version: 2.4
Name: wiktionary-ipa
Version: 0.1.0
Summary: Fast, zero-dependency British English (Received Pronunciation) IPA extractor, normalizer, and verifier querying en.wiktionary.org live.
Author: Thanh Nguyen
License: MIT
Project-URL: Homepage, https://github.com/thanhqng1510/wiktionary-ipa
Project-URL: Repository, https://github.com/thanhqng1510/wiktionary-ipa
Project-URL: Issues, https://github.com/thanhqng1510/wiktionary-ipa/issues
Keywords: ipa,wiktionary,phonetics,british-english,received-pronunciation,linguistics,pronunciation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# wiktionary-ipa

[![PyPI version](https://img.shields.io/pypi/v/wiktionary-ipa.svg)](https://pypi.org/project/wiktionary-ipa/)
[![Python versions](https://img.shields.io/pypi/pyversions/wiktionary-ipa.svg)](https://pypi.org/project/wiktionary-ipa/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Tests](https://github.com/thanhqng1510/wiktionary-ipa/actions/workflows/test.yml/badge.svg)](https://github.com/thanhqng1510/wiktionary-ipa/actions/workflows/test.yml)

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](https://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

```bash
pip install wiktionary-ipa
```

Or install directly from GitHub:

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

---

## Quick Python API

```python
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:

```bash
# 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:

```bash
python3 -m unittest discover -s tests
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.
