light-captcha 0.0.5

A lightweight CAPTCHA generator for Persian and English digits

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

pip install light-captcha

Quickstart

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

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

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

Custom Colors

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

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

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

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