Metadata-Version: 2.4
Name: melli-code
Version: 1.0.1
Summary: Python library to validate and generate Iranian National Codes (Melli Code).
Author-email: Amirhosein Vedadi <amirhsein.vedadi@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Amirhosein Vedadi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/amirhosein-vedadi/Melli_Code
Project-URL: Repository, https://github.com/amirhosein-vedadi/Melli_Code
Keywords: iran,national code,melli code,validation,generation,کد ملی,ایران
Classifier: Development Status :: 5 - Production/Stable
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.7
Classifier: Programming Language :: Python :: 3.8
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 :: Python Modules
Classifier: Topic :: Utilities
Classifier: Natural Language :: Persian
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Melli Code - Iranian National Code (Python)

[![PyPI version](https://badge.fury.io/py/melli-code.svg)](https://badge.fury.io/py/melli-code)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python versions](https://img.shields.io/pypi/pyversions/melli-code.svg)](https://pypi.org/project/melli-code/)

Python library to validate and generate Iranian National Codes (کد ملی ایران).

This is a Python port and enhancement of the original JavaScript library [majidh1/iranianNationalCode](https://github.com/majidh1/iranianNationalCode).

## Features

* **Validation**: Check if a given 10-digit string is a valid Iranian National Code (`is_valid`, `validate`).
* **Generation**: Generate random, valid Iranian National Codes (`generate`).
* Pure Python, no runtime dependencies.
* Type-hinted and tested.

## Installation

```bash
pip install melli-code
```

## Usage

### Validation

Use `is_valid` for a boolean check, or `validate` to raise `InvalidNationalCode` on failure.

```python
from melli_code import is_valid, validate, InvalidNationalCode

# Using is_valid (returns True/False)
code1 = "0012345679"  # Valid
code2 = "0012345678"  # Invalid checksum
code3 = "1111111111"  # Invalid (all same digits)
code4 = "12345"       # Invalid format

print(f"'{code1}' is valid: {is_valid(code1)}")
print(f"'{code2}' is valid: {is_valid(code2)}")
print(f"'{code3}' is valid: {is_valid(code3)}")
print(f"'{code4}' is valid: {is_valid(code4)}")

# Using validate (raises exception on failure)
try:
    validate(code1)
    print(f"'{code1}' validation passed!")
except InvalidNationalCode as e:
    print(f"Validation failed for '{code1}': {e}")

try:
    validate(code2)
    print(f"'{code2}' validation passed!")
except InvalidNationalCode as e:
    print(f"Validation failed for '{code2}': {e}") # Expected output

try:
    validate(code4)
    print(f"'{code4}' validation passed!")
except InvalidNationalCode as e:
    print(f"Validation failed for '{code4}': {e}") # Expected output
```

### Generation

Generate a new, random, valid code.

```python
from melli_code import generate

new_code = generate()
print(f"Generated valid code: {new_code}")
# Example Output: Generated valid code: 4848948377 (will vary)
```

## Algorithm Reference

<img style="max-width:80%" src="https://raw.githubusercontent.com/majidh1/iranianNationalCode/master/sakhtare-codemeli.jpg" alt="Structure of Iranian National Code">
<br />
<img style="max-width:80%" src="https://raw.githubusercontent.com/majidh1/iranianNationalCode/master/algorithm-codemeli.jpeg" alt="Algorithm for Iranian National Code">

(Images from the original JavaScript repository)

## Development

1. Clone the repository:
```bash
git clone https://github.com/amirhosein-vedadi/Melli_Code.git
cd melli-code-py
```

2. Create virtual env:
```bash
python -m venv venv
```

3. Activate:
   - Linux/macOS: `source venv/bin/activate`
   - Windows: `venv\Scripts\activate`

4. Install editable with dev deps:
```bash
pip install -e .[dev]
```

5. Run tests:
```bash
pytest tests/
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgements

* Based on the original JavaScript code by [Majid Hooshiyar](https://github.com/majidh1/iranianNationalCode).
