Metadata-Version: 2.4
Name: light-captcha
Version: 0.0.5
Summary: A lightweight CAPTCHA generator for Persian and English digits
Home-page: https://github.com/COD332/light-captcha
Author: Alireza Esameilzadeh
License-Expression: MIT
Project-URL: Homepage, https://github.com/COD332/light-captcha
Project-URL: Repository, https://github.com/COD332/light-captcha
Project-URL: Issues, https://github.com/COD332/light-captcha/issues
Keywords: captcha,persian,english,security,image,generation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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 :: Security
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=8.0.0
Requires-Dist: importlib_resources>=1.3.0; python_version < "3.9"
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Light Captcha

A lightweight Python library for generating CAPTCHA images with Persian (۰-۹) and English (0-9) digits.

## Features

- Supports Persian and English numerals
- Random digit skewing and rotation
- Size variations per digit
- Millisecond-based random number generation
- Wave distortion effects
- Random color schemes
- Noise and interference patterns
- Customizable image dimensions
- Output as PIL Image or base64 string
- Select PNG, JPG, or animated GIF output formats
- Reliable font loading across platforms (v0.0.3)

## Installation

```bash
pip install light-captcha
```

## Quickstart

```python
from light_captcha import CaptchaGenerator

generator = CaptchaGenerator()

# English CAPTCHA as PIL Image (default)
result = generator.generate("english")
image = result.data
number = result.code
image.save("captcha_english.png")
print(f"Generated number: {number}")

# Persian CAPTCHA as base64 string (PNG by default)
result = generator.generate("persian")
base64_str = result.base64
number = result.code
print(f"Generated number: {number}")
print(f"Base64 data: {base64_str[:50]}...")
```

## API Reference

### CaptchaGenerator

#### generate(language, width=250, height=80, bg_color=None, text_color=None, type="image", format="png")

Generate a CAPTCHA image.

Parameters:
- language (str): "english" or "persian"
- width (int): image width in pixels (default: 250)
- height (int): image height in pixels (default: 80)
- bg_color (tuple, optional): RGB background color
- text_color (tuple, optional): RGB text color
- type (str): must be "image" (default: "image")
- format (str): "png", "jpg", or "gif" (default: "png")

Returns:
- CaptchaResult: object with code, data, base64, and type attributes
    - data: PIL Image
    - base64: base64 string
    - type: MIME type ("image/png", "image/jpeg", or "image/gif")

Raises:
- ValueError: invalid language, type, or format
- FileNotFoundError: missing font file in the package

## Advanced Usage

### Output Formats

```python
result = generator.generate("english", type="image", format="png")
image = result.data
image.save("captcha.png")

result = generator.generate("english", type="image", format="jpg")
base64_str = result.base64
html_img = f'<img src="data:{result.type};base64,{base64_str}" alt="CAPTCHA">'

result = generator.generate("english", type="image", format="gif")
gif_base64 = result.base64
html_gif = f'<img src="data:{result.type};base64,{gif_base64}" alt="CAPTCHA">'
```

### Custom Dimensions

```python
result = generator.generate("english", width=300, height=100)
image = result.data
```

### Custom Colors

```python
bg_color = (240, 248, 255)
text_color = (25, 25, 112)
result = generator.generate(
    "english",
    bg_color=bg_color,
    text_color=text_color,
    type="image"
)
image = result.data
```

### Web Integration

```python
result = generator.generate(
    language="english",
    width=250,
    height=80,
    type="image"
)
base64_captcha = result.base64
correct_answer = result.code

# Store correct_answer in session for validation
# Send base64_captcha to frontend
```

### Batch Generation

```python
for i in range(5):
    result = generator.generate("persian", type="image", format="png")
    image = result.data
    image.save(f"captcha_img_{i}.png")

    result = generator.generate("english", type="image", format="jpg")
    base64_str = result.base64
    number = result.code
    with open(f"captcha_b64_{i}.txt", "w") as f:
        f.write(base64_str)

    print(f"CAPTCHA {i}: {number}")
```

## Error Handling

```python
try:
    generator.generate(language="invalid")
except ValueError as exc:
    print(f"Invalid language: {exc}")
```

## Security Notes

- Random rotation per digit: -15 to +15 degrees
- Random scaling: 0.8x to 1.2x
- Wave distortion with noise lines and dots
- Multiple predefined color palettes
- Millisecond-based seeding

## Compatibility

- Python 3.7+
- Pillow >= 8.0.0
- importlib_resources >= 1.3.0 (Python < 3.9)

## What's New in v0.0.5

- Renamed input to `type` (default: "image")
- Output now includes `data` (PIL), `base64`, `code`, and MIME `type`
- Added animated GIF output for image mode

## What's New in v0.0.3

- Font loading now reads font data into memory for reliable installs
- Resource loading fallback chain improved for cross-platform consistency

## License

MIT License - see LICENSE for details.

## Contributing

Issues and pull requests are welcome on GitHub:
https://github.com/COD332/light-captcha
