egyid 1.0.0__tar.gz

egyid-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petter0x1
+
+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.

egyid-1.0.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: egyid
+Version: 1.0.0
+Summary: A Python library for parsing, validating, and generating Egyptian National IDs
+Author: Petter0x1
+License: MIT License
+        
+        Copyright (c) 2026 Petter0x1
+        
+        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/Petter0x1/egyid
+Project-URL: Repository, https://github.com/Petter0x1/egyid
+Project-URL: Issues, https://github.com/Petter0x1/egyid/issues
+Keywords: egypt,national-id,validation,parsing,generation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Egyptian National ID
+
+[![PyPI version](https://img.shields.io/pypi/v/egyid.svg)](https://pypi.org/project/egyid/)
+[![Python versions](https://img.shields.io/pypi/pyversions/egyid.svg)](https://pypi.org/project/egyid/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Petter0x1/egyid/actions/workflows/ci.yml/badge.svg)](https://github.com/Petter0x1/egyid/actions)
+
+A lightweight and comprehensive Python library for validating, parsing, and generating Egyptian National ID numbers. Built with type hints and designed for reliability in production environments.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Author](#author)
+
+## Features
+
+- **Validation**: Comprehensive ID validation including checksum verification, date validation, and governorate checks
+- **Parsing**: Extract birth date, gender, age, governorate, and region information from ID numbers
+- **Generation**: Create valid mock Egyptian National IDs for testing and development
+- **Type Safety**: Full type hints for better IDE support and code reliability
+- **Arabic Support**: Handles Arabic numerals in ID input
+- **Cross-Platform**: Compatible with Python 3.8+
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install egyid
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Petter0x1/egyid.git
+cd egyid
+pip install .
+```
+
+### Requirements
+
+- Python 3.8 or higher
+- No external dependencies
+
+## Quick Start
+
+```python
+from egyid import EgyptianNationalId
+
+# Validate an ID
+is_valid = EgyptianNationalId.is_valid_id("29010280165195")
+print(is_valid)  # True
+
+# Parse an ID
+eid = EgyptianNationalId("29010280165195")
+if eid.is_valid():
+    print(f"Birth Date: {eid.birth_date}")  # 1990-10-28
+    print(f"Gender: {eid.gender}")          # male
+    print(f"Governorate: {eid.governorate}") # Cairo
+    print(f"Age: {eid.age}")                # 35 (as of 2026)
+    print(f"Region: {eid.region_name}")     # Cairo
+
+# Generate a new ID
+new_id = EgyptianNationalId.generate({
+    "year": 1995,
+    "gender": "female",
+    "governorate": "01"  # Cairo
+})
+print(new_id)  # e.g., "39501010100000" (with correct checksum)
+
+# Get full information as dictionary
+info = eid.to_dict()
+print(info)
+# {
+#     "nationalId": "29010280165195",
+#     "birthYear": 1990,
+#     "birthMonth": 10,
+#     "birthDay": 28,
+#     "age": 35,
+#     "gender": "male",
+#     "governorate": "Cairo",
+#     "region": "Cairo",
+#     "insideEgypt": true,
+#     "isAdult": true
+# }
+```
+
+## API Reference
+
+### Class: `EgyptianNationalId`
+
+#### Methods
+
+- `EgyptianNationalId(id_value: Union[str, int])` - Create an instance from an ID string or integer
+- `is_valid() -> bool` - Check if the ID is valid
+- `to_dict() -> Optional[Dict[str, Any]]` - Return ID information as a dictionary (None if invalid)
+
+#### Properties
+
+- `birth_date: Optional[date]` - Birth date
+- `age: Optional[int]` - Current age
+- `gender: str` - 'male' or 'female'
+- `governorate: Optional[str]` - Governorate name
+- `region_name: str` - Region name
+
+#### Class Methods
+
+- `is_valid_id(id_value: Union[str, int]) -> bool` - Validate without creating instance
+- `generate(options: Optional[Dict[str, Any]] = None) -> str` - Generate a new valid ID
+- `parse(id_value: Union[str, int]) -> EgyptianNationalId` - Alias for constructor
+- `check_is_male(id_value: Union[str, int]) -> bool` - Check if ID belongs to male
+- `check_is_female(id_value: Union[str, int]) -> bool` - Check if ID belongs to female
+- `check_is_adult(id_value: Union[str, int]) -> bool` - Check if person is 18+
+
+### Generation Options
+
+The `generate()` method accepts an optional dictionary with:
+- `year: int` - Birth year (default: random 1950-current)
+- `month: int` - Birth month (default: random 1-12)
+- `day: int` - Birth day (default: valid for month/year)
+- `gender: str` - 'male' or 'female' (default: random)
+- `governorate: str` - 2-digit governorate code (default: random)
+
+## Testing
+
+Run the test suite:
+
+```bash
+python -m unittest discover tests
+```
+
+Tests cover validation, parsing, generation, and edge cases across all supported Python versions.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/Petter0x1/egyid.git
+cd egyid
+python -m venv venv
+venv\Scripts\activate  # On Windows
+pip install -e .
+python -m unittest discover tests
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+@Petter0x1

egyid-1.0.0/README.md

@@ -0,0 +1,167 @@
+# Egyptian National ID
+
+[![PyPI version](https://img.shields.io/pypi/v/egyid.svg)](https://pypi.org/project/egyid/)
+[![Python versions](https://img.shields.io/pypi/pyversions/egyid.svg)](https://pypi.org/project/egyid/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Petter0x1/egyid/actions/workflows/ci.yml/badge.svg)](https://github.com/Petter0x1/egyid/actions)
+
+A lightweight and comprehensive Python library for validating, parsing, and generating Egyptian National ID numbers. Built with type hints and designed for reliability in production environments.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Author](#author)
+
+## Features
+
+- **Validation**: Comprehensive ID validation including checksum verification, date validation, and governorate checks
+- **Parsing**: Extract birth date, gender, age, governorate, and region information from ID numbers
+- **Generation**: Create valid mock Egyptian National IDs for testing and development
+- **Type Safety**: Full type hints for better IDE support and code reliability
+- **Arabic Support**: Handles Arabic numerals in ID input
+- **Cross-Platform**: Compatible with Python 3.8+
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install egyid
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Petter0x1/egyid.git
+cd egyid
+pip install .
+```
+
+### Requirements
+
+- Python 3.8 or higher
+- No external dependencies
+
+## Quick Start
+
+```python
+from egyid import EgyptianNationalId
+
+# Validate an ID
+is_valid = EgyptianNationalId.is_valid_id("29010280165195")
+print(is_valid)  # True
+
+# Parse an ID
+eid = EgyptianNationalId("29010280165195")
+if eid.is_valid():
+    print(f"Birth Date: {eid.birth_date}")  # 1990-10-28
+    print(f"Gender: {eid.gender}")          # male
+    print(f"Governorate: {eid.governorate}") # Cairo
+    print(f"Age: {eid.age}")                # 35 (as of 2026)
+    print(f"Region: {eid.region_name}")     # Cairo
+
+# Generate a new ID
+new_id = EgyptianNationalId.generate({
+    "year": 1995,
+    "gender": "female",
+    "governorate": "01"  # Cairo
+})
+print(new_id)  # e.g., "39501010100000" (with correct checksum)
+
+# Get full information as dictionary
+info = eid.to_dict()
+print(info)
+# {
+#     "nationalId": "29010280165195",
+#     "birthYear": 1990,
+#     "birthMonth": 10,
+#     "birthDay": 28,
+#     "age": 35,
+#     "gender": "male",
+#     "governorate": "Cairo",
+#     "region": "Cairo",
+#     "insideEgypt": true,
+#     "isAdult": true
+# }
+```
+
+## API Reference
+
+### Class: `EgyptianNationalId`
+
+#### Methods
+
+- `EgyptianNationalId(id_value: Union[str, int])` - Create an instance from an ID string or integer
+- `is_valid() -> bool` - Check if the ID is valid
+- `to_dict() -> Optional[Dict[str, Any]]` - Return ID information as a dictionary (None if invalid)
+
+#### Properties
+
+- `birth_date: Optional[date]` - Birth date
+- `age: Optional[int]` - Current age
+- `gender: str` - 'male' or 'female'
+- `governorate: Optional[str]` - Governorate name
+- `region_name: str` - Region name
+
+#### Class Methods
+
+- `is_valid_id(id_value: Union[str, int]) -> bool` - Validate without creating instance
+- `generate(options: Optional[Dict[str, Any]] = None) -> str` - Generate a new valid ID
+- `parse(id_value: Union[str, int]) -> EgyptianNationalId` - Alias for constructor
+- `check_is_male(id_value: Union[str, int]) -> bool` - Check if ID belongs to male
+- `check_is_female(id_value: Union[str, int]) -> bool` - Check if ID belongs to female
+- `check_is_adult(id_value: Union[str, int]) -> bool` - Check if person is 18+
+
+### Generation Options
+
+The `generate()` method accepts an optional dictionary with:
+- `year: int` - Birth year (default: random 1950-current)
+- `month: int` - Birth month (default: random 1-12)
+- `day: int` - Birth day (default: valid for month/year)
+- `gender: str` - 'male' or 'female' (default: random)
+- `governorate: str` - 2-digit governorate code (default: random)
+
+## Testing
+
+Run the test suite:
+
+```bash
+python -m unittest discover tests
+```
+
+Tests cover validation, parsing, generation, and edge cases across all supported Python versions.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/Petter0x1/egyid.git
+cd egyid
+python -m venv venv
+venv\Scripts\activate  # On Windows
+pip install -e .
+python -m unittest discover tests
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+@Petter0x1

egyid-1.0.0/egyid/__init__.py

@@ -0,0 +1,3 @@
+from .id import EgyptianNationalId
+
+__all__ = ["EgyptianNationalId"]

egyid-1.0.0/egyid/generator.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import calendar
+import random
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from .governorates import GOVERNORATES
+from .validation import compute_check_digit
+
+
+def generate_id(options: Optional[Dict[str, Any]] = None) -> str:
+    opts = options or {}
+
+    year = opts.get("year", random.randint(1950, datetime.now().year))
+    month = opts.get("month", random.randint(1, 12))
+    max_day = calendar.monthrange(year, month)[1]
+    day = opts.get("day", random.randint(1, max_day))
+
+    if "governorate" in opts:
+        gov = str(opts["governorate"]).zfill(2)
+    else:
+        gov = random.choice(list(GOVERNORATES.keys()))
+
+    century_digit = 3 if year >= 2000 else 2
+    year_digits = str(year)[-2:]
+    month_digits = str(month).zfill(2)
+    day_digits = str(day).zfill(2)
+
+    if "gender" in opts:
+        is_female = opts["gender"] == "female"
+    else:
+        is_female = bool(random.getrandbits(1))
+
+    sequence_start = str(random.randint(0, 999)).zfill(3)
+    gender_digit = random.randint(0, 4) * 2 if is_female else random.randint(0, 4) * 2 + 1
+
+    id_without_check = (
+        f"{century_digit}{year_digits}{month_digits}{day_digits}{gov}{sequence_start}{gender_digit}"
+    )
+
+    check_digit = compute_check_digit(id_without_check)
+    return id_without_check + str(check_digit)
+
+
+__all__ = ["generate_id"]

egyid-1.0.0/egyid/governorates.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Dict, Optional, TypedDict
+
+
+class GovernorateInfo(TypedDict):
+    name: str
+    region: str
+
+
+GOVERNORATES: Dict[str, GovernorateInfo] = {
+    "01": {"name": "Cairo", "region": "Cairo"},
+    "02": {"name": "Alexandria", "region": "Alexandria"},
+    "03": {"name": "Port Said", "region": "Canal"},
+    "04": {"name": "Suez", "region": "Canal"},
+    "11": {"name": "Damietta", "region": "Delta"},
+    "12": {"name": "Dakahlia", "region": "Delta"},
+    "13": {"name": "Ash Sharqia", "region": "Delta"},
+    "14": {"name": "Kalyubia", "region": "Delta"},
+    "15": {"name": "Kafr El Sheikh", "region": "Delta"},
+    "16": {"name": "Gharbia", "region": "Delta"},
+    "17": {"name": "Monufia", "region": "Delta"},
+    "18": {"name": "Beheira", "region": "Delta"},
+    "19": {"name": "Ismailia", "region": "Canal"},
+    "21": {"name": "Giza", "region": "Upper Egypt"},
+    "22": {"name": "Beni Suef", "region": "Upper Egypt"},
+    "23": {"name": "Fayoum", "region": "Upper Egypt"},
+    "24": {"name": "Minya", "region": "Upper Egypt"},
+    "25": {"name": "Assiut", "region": "Upper Egypt"},
+    "26": {"name": "Sohag", "region": "Upper Egypt"},
+    "27": {"name": "Qena", "region": "Upper Egypt"},
+    "28": {"name": "Aswan", "region": "Upper Egypt"},
+    "29": {"name": "Luxor", "region": "Upper Egypt"},
+    "31": {"name": "Red Sea", "region": "Frontier"},
+    "32": {"name": "New Valley", "region": "Frontier"},
+    "33": {"name": "Matrouh", "region": "Frontier"},
+    "34": {"name": "North Sinai", "region": "Frontier"},
+    "35": {"name": "South Sinai", "region": "Frontier"},
+    "88": {"name": "Outside the Republic", "region": "Foreign"},
+}
+
+
+def get_governorate_info(code: str) -> Optional[GovernorateInfo]:
+    return GOVERNORATES.get(code)
+
+
+def get_governorate_name(code: str) -> Optional[str]:
+    info = get_governorate_info(code)
+    return info["name"] if info else None
+
+
+def get_region(code: str) -> str:
+    info = get_governorate_info(code)
+    return info.get("region", "Foreign") if info else "Foreign"
+
+
+__all__ = ["GovernorateInfo", "GOVERNORATES", "get_governorate_info", "get_governorate_name", "get_region"]

egyid-1.0.0/egyid/id.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+from datetime import date
+from typing import Any, Dict, Optional, Union
+from .generator import generate_id
+from .governorates import get_governorate_name, get_region
+from .utils import sanitize_id
+from .validation import is_valid_id_str
+
+
+class EgyptianNationalId:
+    def __init__(self, id_value: Union[str, int]) -> None:
+        """Create a new instance from a raw ID value.
+
+        The value is converted to string and sanitized immediately.
+        """
+        self.id_str: str = sanitize_id(f"{id_value}")
+
+    def __repr__(self) -> str:
+        return f"<EgyptianNationalId {self.id_str}>"
+
+    @staticmethod
+    def sanitize(id_value: str) -> str:
+        return sanitize_id(id_value)
+
+    @classmethod
+    def parse(cls, id_value: Union[str, int]) -> "EgyptianNationalId":
+        return cls(id_value)
+
+    @classmethod
+    def is_valid_id(cls, id_value: Union[str, int]) -> bool:
+        try:
+            return is_valid_id_str(sanitize_id(f"{id_value}"))
+        except Exception:
+            return False
+
+    @classmethod
+    def check_is_male(cls, id_value: Union[str, int]) -> bool:
+        inst = cls(id_value)
+        return inst.is_valid() and inst.is_male()
+
+    @classmethod
+    def check_is_female(cls, id_value: Union[str, int]) -> bool:
+        inst = cls(id_value)
+        return inst.is_valid() and inst.is_female()
+
+    @classmethod
+    def check_is_adult(cls, id_value: Union[str, int]) -> bool:
+        inst = cls(id_value)
+        return inst.is_valid() and inst.is_adult()
+
+    # --- Generator ---
+    @classmethod
+    def generate(cls, options: Optional[Dict[str, Any]] = None) -> str:
+        return generate_id(options)
+
+    def is_valid(self) -> bool:
+        """Return True if the ID conforms to all validation rules."""
+        return is_valid_id_str(self.id_str)
+
+    def get_birth_year(self) -> int:
+        century_digit = int(self.id_str[0])
+        year = int(self.id_str[1:3])
+        century = 1900 if century_digit == 2 else 2000
+        return century + year
+
+    def get_birth_month(self) -> int:
+        return int(self.id_str[3:5])
+
+    def get_birth_day(self) -> int:
+        return int(self.id_str[5:7])
+
+    def get_birth_date(self) -> Optional[date]:
+        try:
+            return date(
+                self.get_birth_year(),
+                self.get_birth_month(),
+                self.get_birth_day(),
+            )
+        except ValueError:
+            return None
+
+    def get_age(self) -> Optional[int]:
+        bd = self.get_birth_date()
+        if bd is None:
+            return None
+        today = date.today()
+        age = today.year - bd.year - ((today.month, today.day) < (bd.month, bd.day))
+        return age
+
+    # convenience property aliases
+    @property
+    def birth_date(self) -> Optional[date]:
+        return self.get_birth_date()
+
+    @property
+    def age(self) -> Optional[int]:
+        return self.get_age()
+
+    @property
+    def gender(self) -> str:
+        return self.get_gender()
+
+    @property
+    def governorate(self) -> Optional[str]:
+        return self.get_governorate_name()
+
+    @property
+    def region_name(self) -> str:
+        return self.get_region()
+
+    def get_governorate_code(self) -> str:
+        return self.id_str[7:9]
+
+    def get_governorate_name(self) -> Optional[str]:
+        return get_governorate_name(self.get_governorate_code())
+
+    def get_region(self) -> str:
+        return get_region(self.get_governorate_code())
+
+    def get_gender(self) -> str:
+        return "female" if int(self.id_str[12]) % 2 == 0 else "male"
+
+    def is_male(self) -> bool:
+        return self.get_gender() == "male"
+
+    def is_female(self) -> bool:
+        return self.get_gender() == "female"
+
+    def is_adult(self) -> bool:
+        age = self.get_age()
+        return age is not None and age >= 18
+
+    def is_inside_egypt(self) -> bool:
+        return self.get_governorate_code() != "88"
+
+    def to_dict(self) -> Optional[Dict[str, Any]]:
+        if not self.is_valid():
+            return None
+        return {
+            "nationalId": self.id_str,
+            "birthYear": self.get_birth_year(),
+            "birthMonth": self.get_birth_month(),
+            "birthDay": self.get_birth_day(),
+            "age": self.get_age(),
+            "gender": self.get_gender(),
+            "governorate": self.get_governorate_name(),
+            "region": self.get_region(),
+            "insideEgypt": self.is_inside_egypt(),
+            "isAdult": self.is_adult(),
+        }

egyid-1.0.0/egyid/utils.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import re
+
+
+def sanitize_id(id_value: str) -> str:
+    """Return digits-only version of the ID, converting Arabic numerals."""
+    trans = str.maketrans("٠١٢٣٤٥٦٧٨٩", "0123456789")
+    cleaned = id_value.translate(trans)
+    return re.sub(r"[^\d]", "", cleaned)
+
+
+__all__ = ["sanitize_id"]

egyid-1.0.0/egyid/validation.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+import re
+from datetime import datetime
+from .governorates import get_governorate_info
+
+
+_MULTIPLIERS = (2, 7, 6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2)
+
+
+def _is_valid_date(year: int, month: int, day: int) -> bool:
+    try:
+        datetime(year, month, day)
+        return True
+    except ValueError:
+        return False
+
+
+def _compute_check_digit(id_without_check: str) -> int:
+    total = sum(int(id_without_check[i]) * _MULTIPLIERS[i] for i in range(13))
+    remainder = total % 11
+    if remainder == 0:
+        return 0
+    else:
+        return (11 - remainder) % 10
+
+
+def is_valid_id_str(id_str: str) -> bool:
+    if not re.fullmatch(r"\d{14}", id_str):
+        return False
+
+    if int(id_str[0]) not in (2, 3):
+        return False
+
+    year = int(id_str[1:3])
+    month = int(id_str[3:5])
+    day = int(id_str[5:7])
+    century = 1900 if int(id_str[0]) == 2 else 2000
+
+    if not _is_valid_date(century + year, month, day):
+        return False
+
+    if century + year > datetime.now().year:
+        return False
+
+    if get_governorate_info(id_str[7:9]) is None:
+        return False
+
+    return (_compute_check_digit(id_str[:13]) == int(id_str[13]))
+
+
+def compute_check_digit(id_without_check: str) -> int:
+    return _compute_check_digit(id_without_check)
+
+
+__all__ = ["is_valid_id_str", "compute_check_digit"]

egyid-1.0.0/egyid.egg-info/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: egyid
+Version: 1.0.0
+Summary: A Python library for parsing, validating, and generating Egyptian National IDs
+Author: Petter0x1
+License: MIT License
+        
+        Copyright (c) 2026 Petter0x1
+        
+        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/Petter0x1/egyid
+Project-URL: Repository, https://github.com/Petter0x1/egyid
+Project-URL: Issues, https://github.com/Petter0x1/egyid/issues
+Keywords: egypt,national-id,validation,parsing,generation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Egyptian National ID
+
+[![PyPI version](https://img.shields.io/pypi/v/egyid.svg)](https://pypi.org/project/egyid/)
+[![Python versions](https://img.shields.io/pypi/pyversions/egyid.svg)](https://pypi.org/project/egyid/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Petter0x1/egyid/actions/workflows/ci.yml/badge.svg)](https://github.com/Petter0x1/egyid/actions)
+
+A lightweight and comprehensive Python library for validating, parsing, and generating Egyptian National ID numbers. Built with type hints and designed for reliability in production environments.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Author](#author)
+
+## Features
+
+- **Validation**: Comprehensive ID validation including checksum verification, date validation, and governorate checks
+- **Parsing**: Extract birth date, gender, age, governorate, and region information from ID numbers
+- **Generation**: Create valid mock Egyptian National IDs for testing and development
+- **Type Safety**: Full type hints for better IDE support and code reliability
+- **Arabic Support**: Handles Arabic numerals in ID input
+- **Cross-Platform**: Compatible with Python 3.8+
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install egyid
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Petter0x1/egyid.git
+cd egyid
+pip install .
+```
+
+### Requirements
+
+- Python 3.8 or higher
+- No external dependencies
+
+## Quick Start
+
+```python
+from egyid import EgyptianNationalId
+
+# Validate an ID
+is_valid = EgyptianNationalId.is_valid_id("29010280165195")
+print(is_valid)  # True
+
+# Parse an ID
+eid = EgyptianNationalId("29010280165195")
+if eid.is_valid():
+    print(f"Birth Date: {eid.birth_date}")  # 1990-10-28
+    print(f"Gender: {eid.gender}")          # male
+    print(f"Governorate: {eid.governorate}") # Cairo
+    print(f"Age: {eid.age}")                # 35 (as of 2026)
+    print(f"Region: {eid.region_name}")     # Cairo
+
+# Generate a new ID
+new_id = EgyptianNationalId.generate({
+    "year": 1995,
+    "gender": "female",
+    "governorate": "01"  # Cairo
+})
+print(new_id)  # e.g., "39501010100000" (with correct checksum)
+
+# Get full information as dictionary
+info = eid.to_dict()
+print(info)
+# {
+#     "nationalId": "29010280165195",
+#     "birthYear": 1990,
+#     "birthMonth": 10,
+#     "birthDay": 28,
+#     "age": 35,
+#     "gender": "male",
+#     "governorate": "Cairo",
+#     "region": "Cairo",
+#     "insideEgypt": true,
+#     "isAdult": true
+# }
+```
+
+## API Reference
+
+### Class: `EgyptianNationalId`
+
+#### Methods
+
+- `EgyptianNationalId(id_value: Union[str, int])` - Create an instance from an ID string or integer
+- `is_valid() -> bool` - Check if the ID is valid
+- `to_dict() -> Optional[Dict[str, Any]]` - Return ID information as a dictionary (None if invalid)
+
+#### Properties
+
+- `birth_date: Optional[date]` - Birth date
+- `age: Optional[int]` - Current age
+- `gender: str` - 'male' or 'female'
+- `governorate: Optional[str]` - Governorate name
+- `region_name: str` - Region name
+
+#### Class Methods
+
+- `is_valid_id(id_value: Union[str, int]) -> bool` - Validate without creating instance
+- `generate(options: Optional[Dict[str, Any]] = None) -> str` - Generate a new valid ID
+- `parse(id_value: Union[str, int]) -> EgyptianNationalId` - Alias for constructor
+- `check_is_male(id_value: Union[str, int]) -> bool` - Check if ID belongs to male
+- `check_is_female(id_value: Union[str, int]) -> bool` - Check if ID belongs to female
+- `check_is_adult(id_value: Union[str, int]) -> bool` - Check if person is 18+
+
+### Generation Options
+
+The `generate()` method accepts an optional dictionary with:
+- `year: int` - Birth year (default: random 1950-current)
+- `month: int` - Birth month (default: random 1-12)
+- `day: int` - Birth day (default: valid for month/year)
+- `gender: str` - 'male' or 'female' (default: random)
+- `governorate: str` - 2-digit governorate code (default: random)
+
+## Testing
+
+Run the test suite:
+
+```bash
+python -m unittest discover tests
+```
+
+Tests cover validation, parsing, generation, and edge cases across all supported Python versions.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/Petter0x1/egyid.git
+cd egyid
+python -m venv venv
+venv\Scripts\activate  # On Windows
+pip install -e .
+python -m unittest discover tests
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+@Petter0x1

egyid-1.0.0/egyid.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+egyid/__init__.py
+egyid/generator.py
+egyid/governorates.py
+egyid/id.py
+egyid/utils.py
+egyid/validation.py
+egyid.egg-info/PKG-INFO
+egyid.egg-info/SOURCES.txt
+egyid.egg-info/dependency_links.txt
+egyid.egg-info/top_level.txt
+tests/test_egyptian_national_id.py

egyid-1.0.0/egyid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

egyid-1.0.0/egyid.egg-info/top_level.txt

@@ -0,0 +1 @@
+egyid

egyid-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "egyid"
+version = "1.0.0"
+description = "A Python library for parsing, validating, and generating Egyptian National IDs"
+authors = [
+  { name = "Petter0x1" }
+]
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+
+keywords = ["egypt", "national-id", "validation", "parsing", "generation"]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Petter0x1/egyid"
+Repository = "https://github.com/Petter0x1/egyid"
+Issues = "https://github.com/Petter0x1/egyid/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["egyid*"]

egyid-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

egyid-1.0.0/tests/test_egyptian_national_id.py

@@ -0,0 +1,218 @@
+import unittest
+from datetime import date
+from egyid import EgyptianNationalId
+
+
+class TestEgyptianNationalId(unittest.TestCase):
+    def test_valid_id(self):
+        # The last digit is a check digit, calculated using the standard Egyptian national ID algorithm.
+        self.assertTrue(EgyptianNationalId.is_valid_id("29001011400014"))
+
+    def test_invalid_id(self):
+        self.assertFalse(EgyptianNationalId.is_valid_id("00000000000000"))
+
+    def test_generate_valid(self):
+        generated = EgyptianNationalId.generate({"year": 1990, "gender": "male", "governorate": "01"})
+        self.assertTrue(EgyptianNationalId.is_valid_id(generated))
+
+
+class TestEgyptianNationalIdComprehensive(unittest.TestCase):
+    """Comprehensive test suite for Egyptian National ID validation and parsing."""
+
+    def test_valid_ids(self):
+        """Test various valid Egyptian National IDs."""
+        valid_ids = [
+            "29001011400014",  # 1990-01-01, Kalyubia, male
+            "29010280165195",  # 1990-10-28, Cairo, male
+            "30105201501238",  # 2001-05-20, Cairo, female
+            "28801010100001",  # 1988-01-01, Cairo, male (adjusted checksum)
+            "29512310123455",  # 1995-12-31, Cairo, female
+        ]
+        for id_str in valid_ids:
+            with self.subTest(id=id_str):
+                self.assertTrue(EgyptianNationalId.is_valid_id(id_str))
+                eid = EgyptianNationalId(id_str)
+                self.assertTrue(eid.is_valid())
+                self.assertIsNotNone(eid.birth_date)
+                self.assertIn(eid.gender, ['male', 'female'])
+                self.assertIsNotNone(eid.governorate)
+
+    def test_invalid_lengths(self):
+        """Test IDs with wrong lengths."""
+        invalid_lengths = [
+            "123",           # Too short
+            "2900101140001", # 13 digits
+            "290010114000145", # 15 digits
+            "",              # Empty
+        ]
+        for id_str in invalid_lengths:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_invalid_century_digits(self):
+        """Test IDs with invalid century digits."""
+        invalid_centuries = [
+            "19001011400014",  # Starts with 1
+            "49001011400014",  # Starts with 4
+            "09001011400014",  # Starts with 0
+        ]
+        for id_str in invalid_centuries:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_invalid_dates(self):
+        """Test IDs with invalid birth dates."""
+        invalid_dates = [
+            "29023011400014",  # Feb 30 (invalid)
+            "29023111400014",  # Feb 31 (invalid)
+            "29013211400014",  # Jan 32 (invalid)
+            "29001311400014",  # Month 13 (invalid)
+            "29010011400014",  # Month 00 (invalid)
+            "29000111400014",  # Day 00 (invalid)
+        ]
+        for id_str in invalid_dates:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_future_dates(self):
+        """Test IDs with future birth dates."""
+        # Assuming current year is 2026, future dates should be invalid
+        future_ids = [
+            "33601011400018",  # 2033-01-01 (future)
+        ]
+        for id_str in future_ids:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_invalid_governorates(self):
+        """Test IDs with invalid governorate codes."""
+        invalid_govs = [
+            "29001000400014",  # Gov 00 (invalid)
+            "29001991400014",  # Gov 99 (invalid)
+            "29001041400014",  # Gov 41 (invalid)
+        ]
+        for id_str in invalid_govs:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_invalid_checksums(self):
+        """Test IDs with wrong check digits."""
+        invalid_checksums = [
+            "29001011400015",  # Wrong checksum
+            "29001011400013",  # Wrong checksum
+            "29001011400010",  # Wrong checksum
+        ]
+        for id_str in invalid_checksums:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_non_numeric_ids(self):
+        """Test IDs with non-numeric characters."""
+        non_numeric = [
+            "2900101140001a",  # Letter
+            "2900101140001 ",  # Space
+            "2900101140001-",  # Dash
+        ]
+        for id_str in non_numeric:
+            with self.subTest(id=id_str):
+                self.assertFalse(EgyptianNationalId.is_valid_id(id_str))
+
+    def test_arabic_numerals(self):
+        """Test IDs with Arabic numerals (should be sanitized)."""
+        arabic_id = "٢٩٠١٠٢٨٠١٦٥١٩٥"  # 29010280165195 in Arabic
+        self.assertTrue(EgyptianNationalId.is_valid_id(arabic_id))
+
+    def test_parsing_methods(self):
+        """Test parsing methods for valid ID."""
+        eid = EgyptianNationalId("29010280165195")
+        self.assertEqual(eid.get_birth_year(), 1990)
+        self.assertEqual(eid.get_birth_month(), 10)
+        self.assertEqual(eid.get_birth_day(), 28)
+        self.assertEqual(eid.birth_date, date(1990, 10, 28))
+        self.assertEqual(eid.gender, "male")
+        self.assertEqual(eid.governorate, "Cairo")
+        self.assertEqual(eid.region_name, "Cairo")
+        self.assertTrue(eid.is_male())
+        self.assertFalse(eid.is_female())
+        self.assertTrue(eid.is_adult())
+        self.assertTrue(eid.is_inside_egypt())
+
+    def test_generation(self):
+        """Test ID generation."""
+        generated = EgyptianNationalId.generate()
+        self.assertTrue(EgyptianNationalId.is_valid_id(generated))
+        self.assertEqual(len(generated), 14)
+
+        # Test with options
+        male_id = EgyptianNationalId.generate({"gender": "male", "year": 1990, "governorate": "01"})
+        self.assertTrue(EgyptianNationalId.is_valid_id(male_id))
+        eid = EgyptianNationalId(male_id)
+        self.assertEqual(eid.get_birth_year(), 1990)
+        self.assertEqual(eid.gender, "male")
+
+    def test_to_dict(self):
+        """Test dictionary output."""
+        eid = EgyptianNationalId("29010280165195")
+        data = eid.to_dict()
+        expected = {
+            "nationalId": "29010280165195",
+            "birthYear": 1990,
+            "birthMonth": 10,
+            "birthDay": 28,
+            "age": 35,  # As of 2025
+            "gender": "male",
+            "governorate": "Cairo",
+            "region": "Cairo",
+            "insideEgypt": True,
+            "isAdult": True,
+        }
+        self.assertEqual(data, expected)
+
+    def test_invalid_to_dict(self):
+        """Test to_dict returns None for invalid IDs."""
+        eid = EgyptianNationalId("00000000000000")
+        self.assertIsNone(eid.to_dict())
+
+    def test_class_methods(self):
+        """Test class methods for quick checks."""
+        self.assertTrue(EgyptianNationalId.check_is_male("29010280165195"))
+        self.assertFalse(EgyptianNationalId.check_is_female("29010280165195"))
+        self.assertTrue(EgyptianNationalId.check_is_adult("29010280165195"))
+
+        self.assertFalse(EgyptianNationalId.check_is_male("30105201501220"))  # Female
+        self.assertTrue(EgyptianNationalId.check_is_female("30105201501220"))
+
+    def test_sanitization(self):
+        """Test ID sanitization."""
+        self.assertEqual(EgyptianNationalId.sanitize("29001011400014"), "29001011400014")
+        self.assertEqual(EgyptianNationalId.sanitize("٢٩٠٠١٠١١٤٠٠٠١٤"), "29001011400014")
+        self.assertEqual(EgyptianNationalId.sanitize("290-010-114-000-14"), "29001011400014")
+
+    def test_edge_cases(self):
+        """Test various edge cases."""
+        # Leap year
+        leap_id = "29602291400018"  # 1996-02-29
+        self.assertTrue(EgyptianNationalId.is_valid_id(leap_id))
+
+        # Non-leap year Feb 29
+        invalid_leap = "29702291400014"  # 1997-02-29 (invalid)
+        self.assertFalse(EgyptianNationalId.is_valid_id(invalid_leap))
+
+        # Century boundary
+        century_1900 = "29912311400019"  # 1999-12-31
+        self.assertTrue(EgyptianNationalId.is_valid_id(century_1900))
+
+        century_2000 = "30101011400014"  # 2001-01-01
+        self.assertTrue(EgyptianNationalId.is_valid_id(century_2000))
+
+    def test_foreign_governorate(self):
+        """Test IDs from outside Egypt."""
+        foreign_id = "29001018800018"  # Gov 88 (Outside Republic)
+        eid = EgyptianNationalId(foreign_id)
+        self.assertEqual(eid.governorate, "Outside the Republic")
+        self.assertEqual(eid.region_name, "Foreign")
+        self.assertFalse(eid.is_inside_egypt())
+
+
+if __name__ == "__main__":
+    unittest.main()