Metadata-Version: 2.4
Name: kannada-ascii-unicode
Version: 0.1.3
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 package for converting Kannada text between legacy ASCII-based representations and modern Unicode text. It is intended for migration, archival, and text-processing workflows where Kannada content may need to move between older encoding forms and Unicode.

## Overview

This package provides:

- conversion from ASCII-style Kannada text to Unicode
- conversion from Unicode Kannada text to ASCII-style output
- file-based conversion for plain text and DOCX documents
- a simple public API for integration into scripts and applications

The implementation uses bundled mapping data and a conversion engine designed for common Kannada transliteration and mapping scenarios.

## Installation

Install from PyPI:

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

## 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ÀÄ
```

A more complete example is included in the sample application:

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

## Public API

The package exposes the following public entry points:

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

The file conversion helpers infer an output path when none is provided and preserve basic formatting for DOCX files.

## Notes on Accuracy and Scope

This package is designed for practical mapping-based conversion and is suitable for many common Kannada transliteration workflows. Some complex or legacy cases may require additional mapping work or manual review. The bundled test suite provides a baseline for expected behavior and should be used as a reference when extending the converter.

## Development

### 1. Create and activate a virtual environment

```bash
python -m venv .venv
.venv\Scripts\Activate.ps1
```

### 2. Install development dependencies

```bash
python -m pip install --upgrade pip
pip install build pytest twine
```

### 3. Run the test suite

```bash
pytest -q
```

### 4. Build the package locally

```bash
python -m build
```

### 5. Validate the distribution files

```bash
twine check dist/*
```

## Release and Publishing

A local publishing helper is available at [publish.ps1](publish.ps1).

```powershell
./publish.ps1
```

The script performs the following steps:

- removes old build artifacts
- builds the package
- validates the distribution with twine
- prompts for a PyPI API token
- uploads the package to PyPI

The repository also contains a GitHub Actions workflow at [.github/workflows/python-publish.yml](.github/workflows/python-publish.yml). It builds the package and can publish to PyPI when configured for a release event.

## Project Structure

- [kannada_converter/](kannada_converter/) - package source and public API
- [kannada_converter/mappings/](kannada_converter/mappings/) - bundled mapping data
- [tests/](tests/) - automated regression tests
- [testapp/](testapp/) - runnable sample application
- [publish.ps1](publish.ps1) - local package publishing helper
- [.github/workflows/python-publish.yml](.github/workflows/python-publish.yml) - CI/CD workflow for packaging and publishing

## Contributing

Contributions are welcome. To contribute:

1. Fork the repository.
2. Create a feature branch with a descriptive name.
3. Make focused changes and update tests where relevant.
4. Run the test suite and build the package locally.
5. Open a pull request with a summary of the change and the validation performed.

## License

This project is licensed under the MIT License.

## Author

Ravikumar Pawar

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