Metadata-Version: 2.4
Name: iraqi-plate
Version: 0.1.1
Summary: Python library for Iraqi vehicle plate normalization, parsing, validation, formatting, and comparison.
Project-URL: Homepage, https://github.com/mg-jordan/vehichle-plate-normalization/tree/py/iraqi-plate
Project-URL: Repository, https://github.com/mg-jordan/vehichle-plate-normalization/tree/py/iraqi-plate
Project-URL: Issues, https://github.com/mg-jordan/vehichle-plate-normalization/issues
Author: Osama Samman, OpenAI
License: MIT
License-File: LICENSE
Keywords: iraq,iraqi,license plate,normalization,validation,vehicle plate
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: twine>=5.1.1; extra == 'dev'
Description-Content-Type: text/markdown

# iraqi-plate

A Python library for parsing, normalizing, validating, formatting, and comparing Iraqi vehicle plate numbers.

It supports two acceptance modes:

- `strict`
- `standard`

It also supports legacy Arabic-letter input in standard mode, returning a canonical normalized value with a legacy warning.

## Features

- Normalize current Iraqi plate numbers into canonical form.
- Parse structural input into explicit components.
- Validate user input and return machine-readable issues.
- Format canonical or parsed plates into canonical, display, or compact styles.
- Compare two inputs by canonical identity.
- Handle separator cleanup and Eastern Arabic digit folding.

## Installation

```bash
pip install iraqi-plate
```

## Quick start

```python
from iraqi_plate import IraqiPlateService, PlateOptions, AcceptanceMode, FormatStyle

svc = IraqiPlateService()

result = svc.normalize_plate("A22153")
print(result.success)
print(result.canonical)

legacy = svc.normalize_plate("ا٢٢١٥٣")
print(legacy.success)
print(legacy.canonical)
print(legacy.warnings)

formatted = svc.format_plate("22A153", style=FormatStyle.DISPLAY)
print(formatted)

same = svc.equals("A22153", "22A153")
print(same)

strict_result = svc.validate_plate(
    "22-A-153",
    options=PlateOptions(mode=AcceptanceMode.STRICT),
)
print(strict_result.is_valid)
```

## API

### `normalize_plate(input, options=None)`

Returns `NormalizeResult` with:

- `success`
- `canonical`
- `plate`
- `corrections`
- `errors`
- `warnings`

### `parse_plate(input, options=None)`

Returns `ParseResult` with structural parsing results.

### `validate_plate(input, options=None)`

Returns `ValidationResult` with:

- `is_valid`
- `plate`
- `issues`

### `format_plate(input_or_plate, style=FormatStyle.CANONICAL, options=None)`

Supported styles:

- `canonical`
- `display`
- `compact`

### `equals(a, b, options=None)`

Compares two inputs by canonical identity.

## Accepted formats

### Strict mode

After cleanup, only canonical current format is accepted:

```text
GGAN{1-5}
```

Where:

- `GG` is between `11` and `29`
- `A` is a Latin uppercase letter
- `N` is `1..5` ASCII digits

### Standard mode

Accepted inputs include:

- canonical current: `22A153`
- shorthand letter first: `A22153`
- shorthand digit first: `22153A`
- legacy Arabic letter first: `ا22153`

Legacy inputs are accepted with a `legacy_number` warning and normalized into canonical identity like:

```text
22ا153
```

## Development

Create a virtual environment, install dev dependencies, then run:

```bash
python -m pip install -e .[dev]
pytest
python -m build
```

## Project metadata

- Author: Osama Samman, OpenAI
- Repository: https://github.com/mg-jordan/vehichle-plate-normalization/tree/py/iraqi-plate
