# InnoCaptcha

---

## 🚀 Project Identity & Versioning
| Badge Type | Markdown Code |
| :--- | :--- |
| **PyPI Version** | [![PyPI Version](https://img.shields.io/pypi/v/InnoCaptcha.svg)](https://pypi.org/project/InnoCaptcha/) |
| **GitHub Release** | [![GitHub Release](https://img.shields.io/github/v/release/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/releases) |
| **GitHub Tag** | [![GitHub Tag](https://img.shields.io/github/v/tag/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/tags) |
| **License** | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/InnoSoft-Company/InnoCaptcha/blob/main/LICENSE) |
| **PyPI Status** | [![PyPI Status](https://img.shields.io/pypi/status/InnoCaptcha.svg)](https://pypi.org/project/InnoCaptcha/)
---

## 📊 Stats & Downloads
| Badge Type | Markdown Code |
| :--- | :--- |
| **Total Downloads (Pepy)** | [![Total Downloads](https://static.pepy.tech/personalized-badge/InnoCaptcha?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/InnoCaptcha) |
| **Monthly Downloads (Pepy)** | [![Monthly Downloads](https://static.pepy.tech/personalized-badge/InnoCaptcha?period=monthly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/project/InnoCaptcha) |
| **Weekly Downloads (Pepy)** | [![Weekly Downloads](https://static.pepy.tech/personalized-badge/InnoCaptcha?period=weekly&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/project/InnoCaptcha) |
| **PyPI Downloads (Daily)** | [![PyPI Downloads](https://img.shields.io/pypi/dd/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |
| **PyPI Downloads (Weekly)** | [![PyPI Downloads](https://img.shields.io/pypi/dw/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |
| **PyPI Downloads (Monthly)** | [![PyPI Downloads](https://img.shields.io/pypi/dm/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |

---

## 🛠️ Activity & Development
| Badge Type | Markdown Code |
| :--- | :--- |
| **Last Commit** | [![GitHub last commit](https://img.shields.io/github/last-commit/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/commits/main) |
| **Commit Activity (Yearly)** | [![GitHub commit activity](https://img.shields.io/github/commit-activity/y/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/graphs/commit-activity) |
| **Contributors** | [![GitHub contributors](https://img.shields.io/github/contributors/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/graphs/contributors) |
| **Repo Size** | [![GitHub repo size](https://img.shields.io/github/repo-size/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **Code Size** | [![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **Top Language** | [![GitHub top language](https://img.shields.io/github/languages/top/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **Language Count** | [![GitHub language count](https://img.shields.io/github/languages/count/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha) |

---

## ✨ Quality & Testing
| Badge Type | Markdown Code |
| :--- | :--- |
| **Build Status** | [![Build Status](https://github.com/InnoSoft-Company/InnoCaptcha/actions/workflows/python-package.yml/badge.svg)](https://github.com/InnoSoft-Company/InnoCaptcha/actions) |
| **Coverage** | [![Coverage](https://img.shields.io/codecov/c/github/InnoSoft-Company/InnoCaptcha)](https://codecov.io/gh/InnoSoft-Company/InnoCaptcha) |
| **Code Quality** | [![Code Quality](https://img.shields.io/lgtm/grade/python/g/InnoSoft-Company/InnoCaptcha)](https://lgtm.com/projects/g/InnoSoft-Company/InnoCaptcha) |
| **Typing** | [![Typing](https://img.shields.io/badge/typing-strict-brightgreen)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **PyPI Types** | [![PyPI - Types](https://img.shields.io/pypi/types/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |

---

## 🐍 Environment & Compatibility
| Badge Type | Markdown Code |
| :--- | :--- |
| **Python Versions** | [![Python Versions](https://img.shields.io/pypi/pyversions/InnoCaptcha.svg)](https://pypi.org/project/InnoCaptcha/) |
| **PyPI Implementation** | [![PyPI Implementation](https://img.shields.io/pypi/implementation/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |
| **PyPI Wheel** | [![PyPI Wheel](https://img.shields.io/pypi/wheel/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |
| **PyPI Format** | [![PyPI Format](https://img.shields.io/pypi/format/InnoCaptcha)](https://pypi.org/project/InnoCaptcha/) |

---

## 🤝 Community & Social
| Badge Type | Markdown Code |
| :--- | :--- |
| **GitHub Stars** | [![GitHub stars](https://img.shields.io/github/stars/InnoSoft-Company/InnoCaptcha?style=social)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **GitHub Forks** | [![GitHub forks](https://img.shields.io/github/forks/InnoSoft-Company/InnoCaptcha?style=social)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **GitHub Watchers** | [![GitHub watchers](https://img.shields.io/github/watchers/InnoSoft-Company/InnoCaptcha?style=social)](https://github.com/InnoSoft-Company/InnoCaptcha) |
| **GitHub Followers** | [![GitHub followers](https://img.shields.io/github/followers/InnoSoft-Company?style=social)](https://github.com/InnoSoft-Company) |
| **GitHub Discussions** | [![GitHub Discussions](https://img.shields.io/github/discussions/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/discussions) |

---

## 🛠️ Support & Maintenance
| Badge Type | Markdown Code |
| :--- | :--- |
| **Open Issues** | [![GitHub issues](https://img.shields.io/github/issues/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/issues) |
| **Closed Issues** | [![GitHub issues-closed](https://img.shields.io/github/issues-closed/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/issues?q=is%3Aissue+is%3Aclosed) |
| **Open PRs** | [![GitHub pull requests](https://img.shields.io/github/issues-pr/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/pulls) |
| **Closed PRs** | [![GitHub pull requests-closed](https://img.shields.io/github/issues-pr-closed/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/pulls?q=is%3Apr+is%3Aclosed) |
| **Milestones** | [![GitHub milestones](https://img.shields.io/github/milestones/open/InnoSoft-Company/InnoCaptcha)](https://github.com/InnoSoft-Company/InnoCaptcha/milestones) |

Structured Egyptian geographical and timezone data for Python.

Provides a complete, offline dataset of Egyptian governorates, cities, landline and mobile area codes, and timezone utilities — with zero dependencies (uses Python standard library only).

[View on GitHub](https://github.com/InnoSoft-Company/InnoCaptcha) | [View on PyPI](https://pypi.org/project/InnoCaptcha/)

---

## Installation

```bash
pip install InnoCaptcha
```

Quick Start

Image CAPTCHA Generation

Generate custom image-based CAPTCHA with configurable text, colors, size, and fonts.

```python
from InnoCaptcha.image import generate_captcha

# Generate a simple CAPTCHA and save it to the current directory
result = generate_captcha("A1b2C3")
print(result)  # {'file_path': '/current/path/captcha.png', 'chars': 'A1b2C3'}

# Save to a specific folder with custom colors and size
result = generate_captcha(
    chars="7Xk9P",
    path="/tmp/captchas",
    format="png",
    bg_color=(255, 255, 255),      # white background
    fg_color=(50, 150, 200),        # blue text
    width=240,
    height=80
)
```

---

generate_captcha()

Parameter Type Default Description
chars str required The text to render in the CAPTCHA image.
path str or None None Directory where the image will be saved. If None, saves to the current working directory.
format str 'png' Image format (e.g., 'png', 'jpeg', 'gif').
bg_color tuple of 3 int (RGB) or None random light color Background color. If None, a random light color is chosen.
fg_color tuple of 3 or 4 int (RGB/RGBA) or None random dark color Foreground (text) color. If None, a random semi‑transparent dark color is generated.
width int or None 160 Image width in pixels. If None, uses default (160).
height int or None 60 Image height in pixels. If None, uses default (60).
fonts list of font paths or None built‑in fonts List of TrueType font file paths to use for text rendering.
font_sizes tuple of int or None (42, 50, 56) Font sizes to randomly pick from.

Returns a dictionary:

```python
{
    'file_path': str,   # full path to the saved image file
    'chars': str        # the original text that was rendered
}
```

---

Additional Functions

· generate_captcha_image(chars, ...) – returns a PIL.Image object instead of saving it.
· generate_captcha_bytes(chars, ...) – returns an in‑memory bytes buffer of the image (useful for serving directly over HTTP).

Example using generate_captcha_bytes:

```python
from InnoCaptcha.image import generate_captcha_bytes
from flask import send_file

buffer = generate_captcha_bytes("XyZ12")
return send_file(buffer, mimetype='image/png')
```

---

Notes

· All CAPTCHA images include random distortions (curve, dots, character warping) and anti‑aliasing for better security.
· The module uses secrets for cryptographically strong randomness.
· For advanced customization, you can pass your own fonts (list of .ttf file paths) and fine‑tune rendering via the module‑level constants (CHARACTER_OFFSET_DX, WORD_SPACE_PROBABILITY, etc.).
---

Requirements

· Python 3.9 or later (uses standard library zoneinfo; for Python 3.8 you may need the backports.zoneinfo package).

---

License

MIT - InnoSoft Company

```