Metadata-Version: 2.4
Name: kannada-ascii-unicode
Version: 0.1.5
Summary: Kannada ASCII ↔ Unicode converter (basic mapping-based)
Author: Ravikumar Pawar
License-Expression: MIT
Project-URL: Homepage, https://github.com/kagapa-blr/py-kannada-ascii-unicode
Project-URL: Repository, https://github.com/kagapa-blr/py-kannada-ascii-unicode
Keywords: kannada,unicode,ascii,conversion,indic,indian-language
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-docx>=1.1.0
Dynamic: license-file

# Kannada ASCII ↔ Unicode Converter

The Kannada ASCII ↔ Unicode Converter is a Python SDK for transforming older Kannada text written in ASCII characters into the corresponding Unicode Kannada characters required by modern applications and systems. It is designed for migration, archival, document processing, and application workflows where legacy Kannada content needs to be displayed and processed correctly in current environments.

## What the SDK does

The package supports:

- ASCII-style Kannada text to Unicode conversion
- Unicode Kannada text to ASCII-style output
- batch-style processing for plain text files
- DOCX document conversion with preserved paragraph and run structure
- a simple public API that can be used from scripts, web services, or desktop apps

## Why this package exists

Older Kannada text is often stored or exchanged using ASCII-based character representations that were used in legacy systems and documents. This SDK provides a practical bridge between those older ASCII Kannada characters and Unicode, which is the modern standard for correct rendering, storage, and interoperability.

## Installation

Install from PyPI:

```bash
pip install kannada-ascii-unicode
```

For local development:

```bash
python -m pip install -e .
```

## Quick start

```python
from kannada_converter import KannadaConverter, ascii_to_unicode, unicode_to_ascii

converter = KannadaConverter()

ascii_text = "PÀÄ"
unicode_text = converter.convert_ascii_to_unicode(ascii_text)
print(unicode_text)  # ಕು

print(unicode_to_ascii("ಕು"))  # PÀÄ
```

## Public API

The SDK exposes a small and focused public API:

```python
from kannada_converter import (
    KannadaConverter,
    ascii_to_unicode,
    ascii_to_unicode_file,
    unicode_to_ascii,
    unicode_to_ascii_file,
)
```

### Core class

```python
from kannada_converter import KannadaConverter

converter = KannadaConverter()
```

### String conversion

```python
converter.convert_ascii_to_unicode("PÀ")
converter.convert_unicode_to_ascii("ಕ")
```

### File conversion

```python
converter.convert_ascii_to_unicode_file("input.txt", "output.txt")
converter.convert_unicode_to_ascii_file("input.docx", "output.docx")
```

If no destination path is provided, the converter will infer one automatically.

## File support

### Plain text files

The text file path handles UTF-8-compatible input and writes converted output while preserving line breaks and spacing.

### DOCX files

The DOCX path uses the same conversion engine for paragraph and run content. It is suitable for converting legacy ASCII-style document content into Unicode and vice versa while retaining the document structure.

## Architecture overview

The package is organized into three main layers:

- Public API: simple entry points for consumers
- Core engine: conversion logic and special-case handling
- Mapping data: bundled JSON mappings for ASCII ↔ Unicode rules

The implementation uses a trie-based matching approach for lookup efficiency and a mapping-driven engine for Kannada-specific behavior.

## Example workflow

```python
from pathlib import Path
from kannada_converter import KannadaConverter

converter = KannadaConverter()
source = Path("sample.txt")
destination = Path("sample.unicode.txt")
converter.convert_ascii_to_unicode_file(source, destination)
```

## Sample application

A runnable sample app is available in [testapp/app.py](testapp/app.py). It demonstrates both string conversion and DOCX conversion.

Run it with:

```bash
python testapp/app.py
```

## Development and testing

Create a virtual environment and install the project in editable mode:

```bash
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .
pip install pytest python-docx
```

Run the test suite:

```bash
pytest -q
```

## Documentation

Additional documentation is available in the [docs/](docs/) folder:

- [docs/developer_guide.md](docs/developer_guide.md)
- [docs/implementation_details.md](docs/implementation_details.md)

## Project structure

- [kannada_converter/](kannada_converter/) - package source and public API
- [kannada_converter/mappings/](kannada_converter/mappings/) - bundled mapping data
- [tests/](tests/) - regression tests driven by mapping JSON data
- [testapp/](testapp/) - sample application
- [references/](references/) - C# reference implementation used for algorithm inspiration
- [publish.ps1](publish.ps1) - local publishing helper

## Contributing

Contributions are welcome. The recommended flow is:

1. Update mapping data or conversion logic.
2. Add or update regression cases in [tests/test_cases.json](tests/test_cases.json).
3. Run the test suite.
4. Open a pull request with a summary of the change.

## License

This project is licensed under the MIT License.

## Author

Ravikumar Pawar

GitHub: https://github.com/kagapa-blr
