Skip to main content
Pre-release

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, regions and possible_postags) emits a DeprecationWarning. The next major release removes it, together with the legacy tugaphone.dialects inventories that read it. For Portuguese pronunciation, use orthography2ipa with the pt-PT lexicon of o2i-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ɾdu vs 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ç/mpt clusters 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/.

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/.


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 lexicon extra 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.

  1. docs/quickstart.md: install, the first lookups, dialects and AO1990.
  2. docs/api.md: every public method and property.
  3. 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)

Source distribution for tugalex 2.4.2a1
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)

Table of built distributions (wheels) for tugalex 2.4.2a1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page