Metadata-Version: 2.4
Name: lingose
Version: 0.4.0
Summary: Offline English lexicon for the IPSM Approach to pronunciation, spelling and meaning
License-Expression: CC-BY-4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: SOURCES.md
Provides-Extra: dev
Requires-Dist: openpyxl<4,>=3.1; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Dynamic: license-file

# Lingose

[中文](README_zh.md)

Lingose is an offline English lexicon for Python. Look up pronunciations, word structure and English–Chinese meanings, browse vocabulary lists, or add pronunciation marks to English text.

Requires **Python 3.11+**. Queries work offline with no third-party runtime dependencies.

## The IPSM Approach

The **[IPSM Approach](https://lingose.com/)** (Integrated Pronunciation, Spelling and Meaning Approach) connects a word's pronunciation, spelling and meaning to support vocabulary learning. It brings together **IPS**, which marks pronunciation on the spelling; **ISM**, which divides a word into morphemes to show its structure; and **IPM**, which explores links between sound and meaning through listening and speaking. Lingose provides IPA, IPS, ISM, IPSM derived from IPS and ISM, meanings and vocabulary categories for use with the approach.

## Install

Install version 0.4.0 from PyPI:

```sh
python -m pip install --upgrade lingose==0.4.0
```

Version 0.4.0 includes reviewed IPS updates for 12,007 words and regenerated IPSM data. The public API and offline runtime format are unchanged from 0.3.0.

## Look up a word

Lingose offers four ways to represent a word: **IPA** for phonetic transcription, **IPS** for pronunciation marks on its spelling, **ISM** for morpheme divisions, and **IPSM** for pronunciation marks combined with those divisions.

```python
import lingose

print(lingose.ipa("apple"))            # ['æpəl']
print(lingose.ips("running"))          # ['rûnning']
print(lingose.ism("running"))          # runn-ing
print(lingose.ipsm("running"))         # ['rûnn-ing']
print(lingose.root_lemma("running"))   # run
print(lingose.meaning("apple", lang="zh"))
```

The uppercase names `IPA()`, `IPS()`, `ISM()` and `IPSM()` remain available; the lowercase names are aliases with identical behavior.

Use `lang="en"` for English meanings. Unavailable pronunciations return `[]`; unavailable meanings and ISM return `None`.

`lookup(word)` returns nine fixed keys: `word`, `ipa`, `ips`, `ism`, `ipsm`, `root_lemma`, `rank`, `meaning` and `labels`. Pronunciation fields are single strings or `None`; `meaning` always has `en` and `zh`. Unknown words keep the input `word`; other scalars and both meanings are `None`, with `labels=[]`.

```python
result = lingose.lookup("Apple")
print(result["word"])  # Apple
print(result["ipa"])   # æpəl
print(result["meaning"]["en"])
```

## Annotate text

```python
print(lingose.annotate_ips("Abandon the book."))
# Åbando̊n ṫhe̊ book.

print(lingose.annotate_ips("Abandon the book.", skip_top=1000))
# Åbando̊n the book.
```

Text keeps its capitalization, spacing and punctuation. Increase `skip_top` to leave more common words and their inflections unchanged; the default is `0`. Words that cannot be converted appear in brackets, such as `[unknownword]`.

## Vocabulary lists

```python
print(lingose.kind("apple", "CET4"))   # True
print(lingose.kind_list("CET4")[:10])  # First ten words in the list
print(lingose.labels())               # All available categories
```

Categories include CET4, CET6, IELTS, TOEFL and Oxford vocabulary lists.

## License and credits

[CC BY 4.0](LICENSE). Original Lingose data and notation by **ZHAN Xianjue**, [lingose.com](https://lingose.com/).

Data sources and third-party credits are documented in [SOURCES.md](SOURCES.md).
