Metadata-Version: 2.4
Name: kashmiri
Version: 1.0.2
Summary: Find Kashmiri words with definitions and audio pronunciations from online CDN sources.
Home-page: https://github.com/izan-majeed/kaeshir-dictionary-data
Author: Izan Majeed
Author-email: Izan Majeed <izanmajeed03@gmail.com>
Maintainer-email: Izan Majeed <izanmajeed03@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/izan-majeed/kaeshir-dictionary-data
Project-URL: Documentation, https://github.com/izan-majeed/kaeshir-dictionary-data#readme
Project-URL: Repository, https://github.com/izan-majeed/kaeshir-dictionary-data
Project-URL: Issues, https://github.com/izan-majeed/kaeshir-dictionary-data/issues
Project-URL: Google Play, https://play.google.com/store/apps/details?id=com.izanmajeed.dictionary
Project-URL: Live Demo, https://izan-majeed.github.io/kaeshirdictionary
Keywords: kashmiri,dictionary,language,nlp,lexical-database
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Kaeshir Dictionary - Python Package (kashmiri)

An open-source English–Kashmiri lexical database with Python package access, powering the [Kaeshir Dictionary](https://play.google.com/store/apps/details?id=com.izanmajeed.dictionary) platform. Freely available for educational, research, software development or any purpose related to the Kashmiri language.

<p align="center">
  <a href="https://play.google.com/store/apps/details?id=com.izanmajeed.dictionary">
    <img src="https://img.shields.io/badge/Google_Play-Kaeshir_Dictionary-blue?logo=googleplay&logoColor=white">
  </a>
  <a href="https://izan-majeed.github.io/kaeshirdictionary">
    <img src="https://img.shields.io/badge/Web-Live_Demo-orange">
  </a>
  <a href="https://pypi.org/project/kashmiri/">
    <img src="https://img.shields.io/badge/PyPI-kashmiri-green?logo=python&logoColor=white">
  </a>
</p>

---

## Table of Contents

- [About](#about)
- [Features](#features)
- [API Reference](#api-reference)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Finding a Word](#finding-a-word)
  - [Getting All Words](#getting-all-words)
  - [Understanding Different Data Formats](#understanding-different-data-formats)
- [Migration Guide](#migration-guide)
- [Development](#development)
- [Contributing](#contributing)
- [Acknowledgments](#acknowledgments)
- [License](#license)
- [Contact](#contact)

---

## About

This repository serves as both the open-source data repository and the Python package for **Kaeshir Dictionary**, launched in October 2020. The objective is to make Kashmiri resources openly available for anyone building language technologies, educational tools or conducting linguistic research. Rather than keeping the dataset locked inside an application, it is published here so the community can study, improve and reuse it.

---

## Features

**Comprehensive Dataset** - 28,718+ Kashmiri words from multiple authoritative sources  
**Audio Pronunciations** - 2,919 words with audio URLs  
**Fast Search** - Efficient binary search with in-memory caching  
**Multiple Sources** - Data from Sheeba Hassan, Grierson, and curated collections  
**Easy Integration** - With jsDelivr CDN and Python package
**Open Source** - MIT licensed for any use

---

## API Reference

You can access the data directly from the jsDelivr CDN without installing the Python package. The following endpoints are available:

- [Audio Words](https://cdn.jsdelivr.net/gh/izan-majeed/kaeshir-dictionary-data@main/kashmiri/data/audio-words.json)
- [Dictionary Words](https://cdn.jsdelivr.net/gh/izan-majeed/kaeshir-dictionary-data@main/kashmiri/data/dictionary-words.json)
- [Collected Words](https://cdn.jsdelivr.net/gh/izan-majeed/kaeshir-dictionary-data@main/kashmiri/data/collected-words.json)

---

## Installation

Install the Python package via pip:

```bash
pip install kashmiri
```

### Requirements

- Python 3.7 or higher
- No external dependencies (uses only standard library)

---

## Quick Start

```python
from kashmiri import find, get_all_words

# Find a specific word
word_info = find("water")
print(word_info)
# Output: {'word': 'water', 'meaning': '...'}

# Get all words
all_words = get_all_words()
print(f"Total words: {len(all_words)}")
# Output: Total words: 28718

# Search is case-insensitive
find("WATER") == find("water")  # True
```

---

## Dataset

The repository contains three complementary JSON files with Kashmiri lexical data:

### 1. audio-words.json

Words with audio pronunciations (sourced from the work of Sheeba Hassan)

**Schema:**

```json
{
  "word": "ā",
  "audioUrl": "https://dsal.uchicago.edu/dictionaries/hassan/audio/00404.mp3",
  "desc": "interj. a"
}
```

### 2. dictionary-words.json

English-to-Kashmiri dictionary entries, sourced from Grierson

**Schema:**

```json
{
  "word": "āb",
  "meaning": "m. water. This word is generally employed by Musalmāns..."
}
```

### 3. collected-words.json

A curated subset of words collected manually from various sources

**Schema:**

```json
{
  "title": "Abandoned",
  "pos": "/ ə-ˈban-dənd/, adjective",
  "englishMeaning": "Trovmut (m.)",
  "kashmiriMeaning": "ترٛومُت",
  "englishExample": "An abandoned factory.",
  "kashmiriExample": "Akh traivmich factry."
}
```

> **Note:** Field names and structure vary between files. Inspect a few entries in each file before writing a parser rather than assuming a single shared schema across all three.

## Usage

### Finding a Word

Use the `find()` function to search for a word. The returned format depends on which data source contains the word:

```python
>>> from kashmiri import find
>>> from pprint import pprint
>>>
>>> # Example from audio-words.json
>>> find("ablι")
{'word': 'ablι', 'audioUrl': 'https://dsal.uchicago.edu/dictionaries/hassan/audio/00007.mp3', 'desc': 'adj. idiot, stupid, foolish'}
>>>
>>> # Example from dictionary-words.json
>>> find("āb")
{'word': 'āb', 'meaning': 'm. water. This word is generally employed by Musalmāns...'}
>>>
>>> # Example from collected-words.json
>>> x = find('abandoned')
>>> pprint(x)
{'englishExample': 'An abandoned factory.',
 'englishMeaning': 'Trovmut (m.)',
 'kashmiriExample': 'Akh traivmich factry.',
 'kashmiriMeaning': 'ترٛومُت',
 'pos': '/ ə-ˈban-dənd/, adjective',
 'title': 'Abandoned'}
>>>
```

- If the given word is not found, a string saying `Not Found` will be displayed.

```python
>>> find('grep')
Not Found
>>>
```

- Search is `Case Insensitive`

---

## Contributing

We welcome contributions from the community! Whether you want to:

- Report a bug
- Suggest a new feature
- Improve documentation
- Add or correct words
- Contribute code

Please read our [Contributing Guide](CONTRIBUTING.md) to get started.

### Quick Links

- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Development Setup](CONTRIBUTING.md#development-setup)
- [Issue Tracker](https://github.com/izan-majeed/kaeshir-dictionary-data/issues)

---

## Acknowledgments

This project is dedicated to keeping our beloved Kashmiri language alive digitally.

**Special Thanks:**

- **Sheeba Hassan** - Audio pronunciations and phonetic transcriptions
- **Grierson Project** - A Dictionary Of Kashmiri Language

---

## License

Released under the [MIT License](LICENSE). See LICENSE file for details.

---

## Contact

Have questions, ideas, or want to collaborate?

- Email: izanmajeed03@gmail.com
- Issues: [GitHub Issue Tracker](https://github.com/izan-majeed/kaeshir-dictionary-data/issues)
- Web: [Kaeshir Dictionary](https://izan-majeed.github.io/kaeshirdictionary)
- App: [Google Play Store](https://play.google.com/store/apps/details?id=com.izanmajeed.dictionary)

---

<p align="center">
  <strong>Made with ❤️ for the Kaeshir Zabaan</strong>
</p>

```python
>>> find('acʰkan')
{'word': 'acʰkan', 'audioUrl': 'https://dsal.uchicago.edu/dictionaries/hassan/audio/00015.mp3', 'desc': 'n.m. tight long coat with full buttons in front, achkan'}
>>>
>>> find('AcʰKaN')
{'word': 'acʰkan', 'audioUrl': 'https://dsal.uchicago.edu/dictionaries/hassan/audio/00015.mp3', 'desc': 'n.m. tight long coat with full buttons in front, achkan'}
>>>
```

- `AssertionError` will be thrown if you search for some gibberish

```python
>>> find("osama bin laden")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    assert word.isalpha(), "You might be a Haput, else you could have entered a correct word."
AssertionError: You might be a Haput, else you could have entered a correct word.
>>>
```

### Getting All Words

Access the entire database using `get_all_words()`:

```python
>>> from kashmiri import get_all_words
>>> words = get_all_words()
>>> len(words)
28718
>>>
>>> # First few entries (sorted alphabetically)
>>> words[0]
{'englishExample': '-', 'englishMeaning': 'Kehen teh', 'kashmiriExample': '-', 'kashmiriMeaning': 'کٕہنؠ تہِ', 'pos': '/ ˈnən/, pronoun', 'title': None}
>>>
>>> # Find entries with audio
>>> audio_entries = [w for w in words if 'audioUrl' in w]
>>> len(audio_entries)
2919
>>>
```

## Understanding Different Data Formats

Since the data comes from three different sources, you'll encounter three different schemas. Here's how to handle them:

````python
from kashmiri import find

result = find("someword")

if result:
    # Get the word/title (works for all schemas)
    word = result.get('word') or result.get('title')
---

## API Reference

### `find(word: str) -> dict | None`

Find a Kashmiri word and return its details.

**Parameters:**
- `word` (str): The word to search for (case-insensitive, alphabetic characters only)

**Returns:**
- `dict`: Dictionary containing word details in its original schema, or `None` if not found

**Raises:**
- `AssertionError`: If word contains non-alphabetic characters

**Example:**
```python
>>> from kashmiri import find
>>> result = find("water")
>>> print(result)
{'word': 'water', 'meaning': '...'}
````

### `get_all_words() -> list[dict]`

Get all words from the combined database.

**Returns:**

- `list[dict]`: Sorted list of all word entries (28,718+ entries)

**Example:**

```python
>>> from kashmiri import get_all_words
>>> words = get_all_words()
>>> len(words)
28718
```

---

## Migration Guide

Upgrading from version 0.0.1? See the [Migration Guide](MIGRATION.md) for detailed information about:

- Breaking changes
- API updates
- New features
- Schema changes

---

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/izan-majeed/kaeshir-dictionary-data.git
cd kaeshir-dictionary-data

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Running Tests

```bash
# Run pytest
pytest tests/ -v

# Run with coverage
pytest --cov=kashmiri tests/
```

### Code Quality

```bash
# Format code
make format

# Run linters
make lint

# Type checking
mypy kashmiri/
```

### Building and Publishing

```bash
# Build package
make build

# Publish to TestPyPI
make publish-test

# Publish to PyPI (requires credentials)
make publish
```


## Note

The first time you use the `find()` function, it will download the data from the CDN sources. The data is cached in memory for subsequent lookups, making searches very fast.

## What's New in Version 1.0.0

- **Breaking Change:** The package now fetches data from online CDN sources from the [Kaeshir Dictionary Data](https://github.com/izan-majeed/kaeshir-dictionary-data) repository
- **28,718 words** from three different data sources with different schemas:
  - **audio-words.json**: 2,919 words with audio pronunciations (Sheeba Hassan's work)
  - **dictionary-words.json**: 20,643 manually curated words from various sources
  - **collected-words.json**: 5,156 English-to-Kashmiri entries (Grierson's work)
- Data is automatically cached for fast lookups
- New `get_all_words()` function to access all dictionary entries
- Each entry maintains its original schema from its source

For migration information from version 0.0.1, see [MIGRATION.md](MIGRATION.md).

**Note:** The `database.py` file is no longer used and can be safely deleted from your installation.

## Data Schema Reference

| Source                    | Fields                                                                                   | Description                                               |
| ------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **audio-words.json**      | `word`, `audioUrl`, `desc`                                                               | Words with audio pronunciations from Sheeba Hassan's work |
| **dictionary-words.json** | `word`, `meaning`                                                                        | Manually collected words from various sources             |
| **collected-words.json**  | `title`, `pos`, `englishMeaning`, `kashmiriMeaning`, `englishExample`, `kashmiriExample` | English-to-Kashmiri dictionary from Grierson              |

## Credits

- Dictionary data: [Kaeshir Dictionary Data](https://github.com/izan-majeed/kaeshir-dictionary-data)
- Audio pronunciations: Sheeba Hassan
- Package maintainer: Izan Majeed
```
