Metadata-Version: 2.4
Name: lingose
Version: 0.2.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.2.0 from PyPI after release:

```sh
python -m pip install lingose==0.2.0
```

For building from source, see the [maintenance guide](tools/README.md).

The complete lexicon is compressed in the package. The first query restores it offline to a user cache; allow about 1.5 GB of free disk space and time for this initial preparation. Later queries reuse the database. Set `LINGOSE_CACHE_DIR` before starting Python to choose another cache location. Importing the package alone does not restore data.

## 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"))
```

Use `lang="en"` for English meanings. `lookup(word)` returns the full entry, including parts of speech and sources. Unavailable pronunciations return `[]`; unavailable meanings and ISM return `None`.

## 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. See the [API reference](docs/api.md) for all functions and return values.

## 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).
