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.


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,147 to 53,148 words in each region. Regenerate it with python scripts/build_regional_dict.py. 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.2.2a3

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.2.2a3
File Size Uploaded Provenance Actions
tugalex-2.2.2a3.tar.gz 2.7 MB Without provenance Details for tugalex-2.2.2a3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tugalex 2.2.2a3
File Interpreter ABI Platform Actions
tugalex-2.2.2a3-py3-none-any.whl Python 3 none any Details for tugalex-2.2.2a3-py3-none-any.whl

Total release size: 5.5 MB

Release files / tugalex-2.2.2a3.tar.gz

Download URL tugalex-2.2.2a3.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
ce2edccdbce78d90fc1b130e3700e84e7242ad553cc44029486d9ba89c4e7f16
BLAKE2b-256 checksum
How to use checksums
e7956ee059f773476e73ad17a6df8bde76d61e55953e02f7f3204d2c7720008e
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.2.2a3-py3-none-any.whl

Download URL tugalex-2.2.2a3-py3-none-any.whl
Size 2.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
2fe37ff056c24a099bbe31f7987cf2586886f3eb462a27ee939ff87b0ad5080e
BLAKE2b-256 checksum
How to use checksums
1358a05014d189e352d1858f75a47887914e75bb2ce93befb7e65d7f881cd1fb
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.2.2a3

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