kannada-ascii-unicode 0.1.5

Kannada ASCII ↔ Unicode converter (basic mapping-based)

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:

pip install kannada-ascii-unicode

For local development:

python -m pip install -e .

Quick start

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:

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

Core class

from kannada_converter import KannadaConverter

converter = KannadaConverter()

String conversion

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

File conversion

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

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. It demonstrates both string conversion and DOCX conversion.

Run it with:

python testapp/app.py

Development and testing

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

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:

pytest -q

Documentation

Additional documentation is available in the docs/ folder:

• docs/developer_guide.md
• docs/implementation_details.md

Project structure

• kannada_converter/ - package source and public API
• kannada_converter/mappings/ - bundled mapping data
• tests/ - regression tests driven by mapping JSON data
• testapp/ - sample application
• references/ - C# reference implementation used for algorithm inspiration
• 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.
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