Metadata-Version: 2.4
Name: iran-encoding
Version: 0.1.0
Summary: Two-stage encoding for Persian text.
Home-page: https://github.com/example/iran-encoding
Author: Jules
Author-email: jules@example.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=10.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Iran System Encoding
[![Python package CI](https://github.com/movtigroup/Iran-System-encoding/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/movtigroup/Iran-System-encoding/actions/workflows/ci.yml)[![Python Package using Conda](https://github.com/movtigroup/Iran-System-encoding/actions/workflows/python-package-conda.yml/badge.svg)](https://github.com/movtigroup/Iran-System-encoding/actions/workflows/python-package-conda.yml)

A Python package for encoding and decoding text using the Iran System character set, designed for environments like NDS Station Displays.

This library provides a direct mapping from Unicode characters to the custom Iran System byte representation. It includes robust support for both English (LTR) and Persian (RTL) text, automatically handling the complexities of bidirectional text display.

## Key Features

- **Direct Encoding**: A single-stage mapping from Unicode to the Iran System character set.
- **Bidirectional Text Support**: Automatically detects and reverses Right-to-Left (Persian) text segments for correct logical-to-visual ordering, while leaving Left-to-Right (English) segments untouched.
- **Full ASCII and Persian Support**: The character map includes standard ASCII, Persian letters, and Persian digits.
- **Fallback for Unknown Characters**: Gracefully handles characters not in the map by replacing them with a `'?'`.
- **Command-Line Interface**: Includes a CLI tool for easy encoding and decoding from the terminal.

## Installation

To install the package directly from GitHub:

```bash
pip install git+https://github.com/movtigroup/Iran-System-encoding.git
```

## Library Usage

The library provides simple `encode()` and `decode()` functions.

### Example 1: Pure Persian (RTL)

```python
from iran_encoding import encode, decode

text = "سلام دنیا"
encoded = encode(text)
print(f"Original: {text}")
print(f"Encoded: {encoded.hex()}")

decoded = decode(encoded)
print(f"Decoded: {decoded}")
# Correctly prints: سلام دنیا
```

### Example 2: Pure English (LTR)

```python
from iran_encoding import encode, decode

text = "Hello, World!"
encoded = encode(text)
print(f"\nOriginal: {text}")
print(f"Encoded: {encoded.hex()}")

decoded = decode(encoded)
print(f"Decoded: {decoded}")
# Correctly prints: Hello, World!
```

### Example 3: Mixed Bidirectional Text

The library automatically handles the ordering of text segments.

```python
from iran_encoding import encode, decode

text = "Final ETA: ۱۰ دقیقه"
encoded = encode(text)
print(f"\nOriginal: {text}")
print(f"Encoded: {encoded.hex()}")

decoded = decode(encoded)
print(f"Decoded: {decoded}")
# Correctly prints: Final ETA: ۱۰ دقیقه
```

## Command-Line Interface

You can also use the package from the command line.

### `encode`

```bash
iran-encoding encode "Test: تست"
```
This will print the raw encoded bytes to standard output.

### `decode`

The `decode` command requires the input to be a Python bytes literal string.

```bash
iran-encoding decode "b'\\x54\\x65\\x73\\x74\\x3a\\x20\\x91\\x9d\\x8f'"
```
This will print the decoded string: `Test: تست`

**Note**: You need to wrap the byte string in quotes (`" "`) and prefix it with `b''` to ensure it is correctly parsed by the command line.

### `decode-hex`

The `decode-hex` command decodes a string of hexadecimal characters into text.

```bash
iran-encoding decode-hex 546573743a20919d8f
```
This will print the decoded string: `Test: تست`

## WebSocket Support

This library also provides WebSocket support for both a server and a client.

### WebSocket Server

You can start a WebSocket server that will listen for incoming messages and encode or decode them.

```bash
iran-encoding ws-server --host 0.0.0.0 --port 8765
```

The server expects messages in the format `"command:data"`, where `command` is one of `encode`, `decode`, or `decode-hex`.

### WebSocket Client

You can use the WebSocket client to send a message to the server and receive the response.

```bash
iran-encoding ws-client ws://localhost:8765 "encode:سلام"
```
This will send the message `"encode:سلام"` to the server and print the response.
