This release is a pre-release and may not be stable for production use.
TugaLex
TugaLex is a lexicon handler and linguistic utility for Portuguese dialects. It provides data on phoneme transcription (IPA), syllable segmentation, and historical and modern orthographic rules.
It gives NLP pipelines and linguistics research a single API for the differences between Portuguese regions and historical spelling agreements.
Deprecated: the regional pronunciation dictionary. The phoneme and syllable API (
get,get_phonemes,get_syllables,get_wordlist,get_ipa_map,lang_to_region,ipa,syllables,regionsandpossible_postags) emits aDeprecationWarning. The next major release removes it, together with the legacytugaphone.dialectsinventories that read it. For Portuguese pronunciation, use orthography2ipa with the pt-PT lexicon ofo2i-lexicons(orthography2ipa.use_packaged_lexicons). The noun gender, given-name gender and AO1990 tools stay.
Supported Dialects
TugaLex maps standard ISO codes to internal regional datasets:
| ISO Code | Internal Code | Region |
|---|---|---|
pt-PT |
lbx |
Portugal (Lisbon) |
pt-BR |
rjx |
Brazil (Rio de Janeiro) |
| n/a | spx |
Brazil (São Paulo) |
pt-AO |
lda |
Angola (Luanda) |
pt-MZ |
mpx |
Mozambique (Maputo) |
pt-TL |
dli |
Timor-Leste (Díli) |
spx has no ISO alias. Pass it as region="spx".
The regional dictionary ships as a slim gzip extract (word, phones,
syllables, region) of the unified Portuguese pronunciation lexicon,
with 53,142 to 53,145 words in each region. Regenerate it with
python scripts/build_regional_dict.py, which reads the lexicon revision
pinned in the script. The regional dictionary has no
part of speech: each word has one pronunciation per region, and it answers
every POS query. Only the heterophonic homograph table is keyed by POS.
Key Features
1. Phonemes & Syllables
Retrieve IPA transcriptions and syllable breaks for a word in a region. For the 27 heterophonic homographs, the part of speech (POS) selects the pronunciation.
from tugalex import TugaLexicon
lex = TugaLexicon()
# Get both syllables and phonemes
info = lex.get("acordo", pos="NOUN", region="lbx")
# Output: {'syllables': ['a', 'cor', 'do'], 'phonemes': 'ɐˈkoɾdu'}
# POS matters!
verb_phonemes = lex.get_phonemes("acordo", pos="VERB")
# Output: 'ɐˈkɔɾdu'
verb_phonemes = lex.get_phonemes("acordo", pos="NOUN")
# Output: 'ɐˈkoɾdu'
2. Orthographic Agreement (AO1990)
Convert text between pre-agreement and post-agreement (AO1990) spelling for Portugal and Brazil.
- Normalize: Old spelling to modern spelling.
- Reverse: Modern spelling to old regional spelling (PT or BR).
lex.normalize_ao1900("acção óptimo") # 'ação ótimo'
lex.reverse_ao1900_pt("ótimo") # 'óptimo'
The conversion splits on whitespace and matches each word exactly, so a word with attached punctuation or a capital letter is not converted (#46).
3. Linguistic Insights
TugaLex identifies specific linguistic phenomena programmatically:
- Homographs: Words that change pronunciation with POS (e.g., acordo the noun
ɐˈkoɾduvs acordo the verbɐˈkɔɾdu). Two readings with the same POS, such as sede thirst vs headquarters, need bifonia. - Archaic Words: Mapping 19th-century etymological spellings to modern ones.
- Silent Letters: Identifying words with a silent 'p' in the
mpc/mpç/mptclusters of pre-1990 spelling. Silent 'c' detection does not exist (#2). - Voiced 'u': Detecting words where 'u' is pronounced in 'gue/gui/que/qui' clusters (formerly marked with a trema
ü).
4. Noun Gender
Get the grammatical gender of a Portuguese common noun, singular or plural. Suffix rules decide most nouns, and a list of exceptions decides the rest.
TugaLexicon.get_noun_gender("lei") # 'f'
TugaLexicon.get_noun_gender("dias") # 'm'
TugaLexicon.get_noun_gender("artista") # 'mf' (both genders)
5. Given-Name Gender
Get the grammatical gender of a given name, written as in running text. The list holds regnal names, the Brazilian census names that match a Wikidata given name, and the Wikidata given names marked Portuguese.
TugaLexicon.get_given_name_gender("Isabel") # 'f'
TugaLexicon.get_given_name_gender("Afonso") # 'm'
TugaLexicon.get_given_name_gender("Darci") # 'mf' (both genders)
TugaLexicon.get_given_name_gender("Raio") # None
Datasets
TugaLex ships the following datasets under tugalex/data/.
regional_dict.csv.gz: phoneme and syllable mappings, 318,860 rows for 53,146 distinct words in six regions.scripts/build_regional_dict.pybuilds it from the unified Portuguese pronunciation lexicon and keeps six of its Portal da Língua Portuguesa regions. The scraped Portal data with all ten regional variants is theportuguese_phonetic_lexicondataset.heterophonic_homographs.csv: 27 words pronounced differently depending on POS, 55 rows.acordo_ortografico_pt_PT.csv: Portugal old orthographic spellings.acordo_ortografico_pt_BR.csv: Brazil old orthographic spellings.archaisms.csv: normalized words from before the 20th century.
noun_gender_exceptions.csv.gz lists the nouns whose gender the suffix rules
get wrong or do not cover, and the nouns of both genders.
scripts/build_noun_gender.py regenerates it from the noun genders of the
English Wiktionary.
given_names.csv.gz lists given names with their gender.
scripts/build_given_names.py regenerates it from Wikidata (CC0) and the IBGE
2010 census first names published by datasets-br/prenomes (ODC-PDDL-1.0).
scripts/given_name_overrides.csv corrects the names whose Wikidata items
mislead, each with its evidence.
Install
pip install --pre tugalex
TugaLex publishes alpha releases from the dev branch. Use --pre to get the API that this README describes. TugaLex has no third-party runtime dependencies. All datasets ship inside the package under tugalex/data/.
Related Projects
TugaLex is one piece of the TigreGotico Portuguese NLP stack:
- tugaphone: phonemizes arbitrary Portuguese text across dialects, using TugaLex plus a rule-based fallback. tugaphone depends on TugaLex.
- bifonia: picks the reading of a heterophonic homograph by meaning, including the same-POS pairs that the TugaLex homograph table cannot separate.
- tugamorph: rule-based morphological analyzer for Portuguese.
- tugatagger: Part-of-Speech tagging wrapper for Portuguese. Its
lexiconextra installs TugaLex. - desacordo_ortografico: detects and converts between Portuguese orthographies, including the AO1990 reform.
Documentation
Read the pages in this order. Each page links to the next one.
docs/quickstart.md: install, the first lookups, dialects and AO1990.docs/api.md: every public method and property.docs/advanced.md: recipes and gotchas.
Runnable scripts for each feature are in examples/.
Development
| path | contents |
|---|---|
tugalex/__init__.py |
the TugaLexicon class and the noun-gender suffix rules |
tugalex/data/ |
the packaged datasets |
scripts/ |
the build scripts for regional_dict.csv.gz, noun_gender_exceptions.csv.gz and given_names.csv.gz, and their override files |
tests/ |
the pytest suite |
examples/ |
one runnable script per feature |
*.ipynb |
analysis notebooks for the phonetic lexicon and the AO1990 tables |
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --prerelease=allow -e ".[test]"
.venv/bin/python -m pytest tests
CI runs the same suite on Python 3.11 to 3.14 (.github/workflows/build-tests.yml). The build scripts download their sources, so run them only to regenerate a dataset. Each row of scripts/given_name_overrides.csv carries its evidence in the reason column.
License
TugaLex is released under the Apache License 2.0.
Metadata
Release files for tugalex 2.4.2a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tugalex-2.4.2a1.tar.gz | 2.7 MB | Without provenance | Details for tugalex-2.4.2a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tugalex-2.4.2a1-py3-none-any.whl | Python 3 | none | any | Details for tugalex-2.4.2a1-py3-none-any.whl |
Total release size: 5.5 MB
Release files / tugalex-2.4.2a1.tar.gz
| Download URL | tugalex-2.4.2a1.tar.gz |
|---|---|
| Size | 2.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
20c6cf6d9ad0e20f7814b27337c33ab65d6fe9e50920b506e21914f904136d40
|
|
BLAKE2b-256 checksum How to use checksums |
2459b5afc1912d19b320aee5a7e26d5243d0c1b53ee459bddbecbe063ca8e358
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / tugalex-2.4.2a1-py3-none-any.whl
| Download URL | tugalex-2.4.2a1-py3-none-any.whl |
|---|---|
| Size | 2.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd05b743388746f6723e7532e7ab8a99a5802a5767fac2affdd1339d06945e6b
|
|
BLAKE2b-256 checksum How to use checksums |
3c8a0afaf33dd08ef939e7d9652edc1ac6d29861a5e20345412f15c6d6ea8fc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for tugalex 2.4.2a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.