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,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.3.1a1

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.3.1a1
File Size Uploaded Provenance Actions
tugalex-2.3.1a1.tar.gz 2.7 MB Without provenance Details for tugalex-2.3.1a1.tar.gz

Built distribution (wheel)

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

Total release size: 5.5 MB

Release files / tugalex-2.3.1a1.tar.gz

Download URL tugalex-2.3.1a1.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
5c13d44b1532c295aff2d699a5e82de485ee9181a0af9cbb0201b5e2d081e980
BLAKE2b-256 checksum
How to use checksums
36203c170781c7b7e7aca9420f072f54f06b3067bffe653daca5526328323281
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.3.1a1-py3-none-any.whl

Download URL tugalex-2.3.1a1-py3-none-any.whl
Size 2.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f31337f5a17bb802eb73efa506d3a7c98b23eedb5f7a474ce1da70293c84dab3
BLAKE2b-256 checksum
How to use checksums
057fbffd89f8d5f20c23b722ff026b092ea0748507fb5e8f65628e46730d9472
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.3.1a1

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