# Light Captcha
A lightweight Python library for generating CAPTCHA images with Persian (۰-۹) and English (0-9) digits.
## Features
- ✨ Support for both Persian and English numerals
- 🔒 Random digit skewing and rotation for security
- 📏 Size variations for enhanced difficulty
- 🎯 Millisecond-based random number generation
- 🌊 Wave distortion effects
- 🎨 Random color schemes
- 🔧 Enhanced noise and interference patterns
- 📐 Customizable image dimensions
- 🖼️ **NEW in v0.0.2**: Output format options (PIL Image or base64)
- 🔧 **NEW in v0.0.2**: Improved font resource loading for better cross-platform compatibility
## Installation
```bash
pip install light-captcha
```
## Quick Start
```python
from light_captcha import CaptchaGenerator
# Create generator instance
generator = CaptchaGenerator()
# Generate English CAPTCHA as PIL Image (default)
image, number = generator.generate('english')
image.save('captcha_english.png')
print(f"Generated number: {number}")
# Generate Persian CAPTCHA as base64 string
base64_str, number = generator.generate('persian', output='base64')
print(f"Generated number: {number}")
print(f"Base64 data: {base64_str[:50]}...")
```
## Usage Examples
### Output Format Options (New in v0.0.2)
```python
# Generate as PIL Image object (default)
image, number = generator.generate('english', output='image')
image.save('captcha.png')
# Generate as base64 string for web applications
base64_str, number = generator.generate('english', output='base64')
html_img = f'<img src="data:image/png;base64,{base64_str}" alt="CAPTCHA">'
```
### Custom Dimensions
```python
# Generate with custom size
image, number = generator.generate('english', width=300, height=100)
```
### Custom Colors
```python
# Generate with custom colors
bg_color = (240, 248, 255) # Light blue background
text_color = (25, 25, 112) # Navy text
image, number = generator.generate(
'english',
bg_color=bg_color,
text_color=text_color,
output='image'
)
```
### Web Application Integration
```python
generator = CaptchaGenerator()
# For APIs and web frameworks
base64_captcha, correct_answer = generator.generate(
language='english',
width=250,
height=80,
output='base64'
)
# Store correct_answer in session for validation
# Send base64_captcha to frontend
```
### Batch Generation
```python
generator = CaptchaGenerator()
# Generate multiple CAPTCHAs with different formats
for i in range(5):
# Image format
image, number = generator.generate('persian', output='image')
image.save(f'captcha_img_{i}.png')
# Base64 format
base64_str, number = generator.generate('english', output='base64')
with open(f'captcha_b64_{i}.txt', 'w') as f:
f.write(base64_str)
print(f"CAPTCHA {i}: {number}")
```
## API Reference
### CaptchaGenerator
#### `generate(language, width=250, height=80, bg_color=None, text_color=None, output='image')`
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
- `output` (str): `'image'` for PIL Image object or `'base64'` for base64 string (default: 'image')
**Returns:**
- `tuple`: (PIL Image object or base64 string, 6-digit string)
**Raises:**
- `ValueError`: If language is not 'english' or 'persian'
- `ValueError`: If output is not 'image' or 'base64'
- `FileNotFoundError`: If required font file is missing
## What's New in v0.0.2
### Enhanced Font Loading
- Improved font resource loading using `importlib.resources` for better cross-platform compatibility
- Automatic fallback mechanisms for different Python versions
- Resolves PIL font format errors when package is installed system-wide
### Output Format Options
- **Image Output**: Returns PIL Image object (default, backward compatible)
- **Base64 Output**: Returns base64-encoded PNG string for direct web integration
### Better Error Handling
- More descriptive error messages for font loading issues
- Validation for output format parameter
- Improved cross-platform compatibility
## Security Features
- **Random Skewing**: Each digit rotated -15° to +15°
- **Size Variation**: Random scaling 0.8x to 1.2x per digit
- **Wave Distortion**: Sinusoidal distortion across the image
- **Noise Patterns**: Curved lines and random dots
- **Color Randomization**: Multiple predefined color schemes
- **Millisecond Seeding**: High-precision random generation
## Requirements
- Python 3.7+
- Pillow >= 8.0.0
- importlib_resources >= 1.3.0 (for Python < 3.9)
## License
MIT License - see LICENSE file for details.
## Contributing
Issues and pull requests are welcome on [GitHub](https://github.com/COD332/light-captcha).
Raw data
{
"_id": null,
"home_page": "https://github.com/COD332/light-captcha",
"name": "light-captcha",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "captcha, persian, english, security, image, generation",
"author": "Alireza Esameilzadeh",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/21/32/5474e9af6776af6035db597463a848042a3bf90e0b39ff3d0c64e628dd3a/light_captcha-0.0.3.tar.gz",
"platform": null,
"description": "# Light Captcha\n\nA lightweight Python library for generating CAPTCHA images with Persian (\u06f0-\u06f9) and English (0-9) digits.\n\n## Features\n\n- \u2728 Support for both Persian and English numerals\n- \ud83d\udd12 Random digit skewing and rotation for security\n- \ud83d\udccf Size variations for enhanced difficulty \n- \ud83c\udfaf Millisecond-based random number generation\n- \ud83c\udf0a Wave distortion effects\n- \ud83c\udfa8 Random color schemes\n- \ud83d\udd27 Enhanced noise and interference patterns\n- \ud83d\udcd0 Customizable image dimensions\n- \ud83d\uddbc\ufe0f **NEW in v0.0.2**: Output format options (PIL Image or base64)\n- \ud83d\udd27 **NEW in v0.0.2**: Improved font resource loading for better cross-platform compatibility\n\n## Installation\n\n```bash\npip install light-captcha\n```\n\n## Quick Start\n\n```python\nfrom light_captcha import CaptchaGenerator\n\n# Create generator instance\ngenerator = CaptchaGenerator()\n\n# Generate English CAPTCHA as PIL Image (default)\nimage, number = generator.generate('english')\nimage.save('captcha_english.png')\nprint(f\"Generated number: {number}\")\n\n# Generate Persian CAPTCHA as base64 string\nbase64_str, number = generator.generate('persian', output='base64')\nprint(f\"Generated number: {number}\")\nprint(f\"Base64 data: {base64_str[:50]}...\")\n```\n\n## Usage Examples\n\n### Output Format Options (New in v0.0.2)\n\n```python\n# Generate as PIL Image object (default)\nimage, number = generator.generate('english', output='image')\nimage.save('captcha.png')\n\n# Generate as base64 string for web applications\nbase64_str, number = generator.generate('english', output='base64')\nhtml_img = f'<img src=\"data:image/png;base64,{base64_str}\" alt=\"CAPTCHA\">'\n```\n\n### Custom Dimensions\n\n```python\n# Generate with custom size\nimage, number = generator.generate('english', width=300, height=100)\n```\n\n### Custom Colors\n\n```python\n# Generate with custom colors\nbg_color = (240, 248, 255) # Light blue background\ntext_color = (25, 25, 112) # Navy text\nimage, number = generator.generate(\n 'english', \n bg_color=bg_color, \n text_color=text_color,\n output='image'\n)\n```\n\n### Web Application Integration\n\n```python\ngenerator = CaptchaGenerator()\n\n# For APIs and web frameworks\nbase64_captcha, correct_answer = generator.generate(\n language='english',\n width=250, \n height=80,\n output='base64'\n)\n\n# Store correct_answer in session for validation\n# Send base64_captcha to frontend\n```\n\n### Batch Generation\n\n```python\ngenerator = CaptchaGenerator()\n\n# Generate multiple CAPTCHAs with different formats\nfor i in range(5):\n # Image format\n image, number = generator.generate('persian', output='image')\n image.save(f'captcha_img_{i}.png')\n \n # Base64 format \n base64_str, number = generator.generate('english', output='base64')\n with open(f'captcha_b64_{i}.txt', 'w') as f:\n f.write(base64_str)\n \n print(f\"CAPTCHA {i}: {number}\")\n```\n\n## API Reference\n\n### CaptchaGenerator\n\n#### `generate(language, width=250, height=80, bg_color=None, text_color=None, output='image')`\n\nGenerate a CAPTCHA image.\n\n**Parameters:**\n- `language` (str): `'english'` or `'persian'`\n- `width` (int): Image width in pixels (default: 250)\n- `height` (int): Image height in pixels (default: 80) \n- `bg_color` (tuple, optional): RGB background color\n- `text_color` (tuple, optional): RGB text color\n- `output` (str): `'image'` for PIL Image object or `'base64'` for base64 string (default: 'image')\n\n**Returns:**\n- `tuple`: (PIL Image object or base64 string, 6-digit string)\n\n**Raises:**\n- `ValueError`: If language is not 'english' or 'persian'\n- `ValueError`: If output is not 'image' or 'base64' \n- `FileNotFoundError`: If required font file is missing\n\n## What's New in v0.0.2\n\n### Enhanced Font Loading\n- Improved font resource loading using `importlib.resources` for better cross-platform compatibility\n- Automatic fallback mechanisms for different Python versions\n- Resolves PIL font format errors when package is installed system-wide\n\n### Output Format Options\n- **Image Output**: Returns PIL Image object (default, backward compatible)\n- **Base64 Output**: Returns base64-encoded PNG string for direct web integration\n\n### Better Error Handling\n- More descriptive error messages for font loading issues\n- Validation for output format parameter\n- Improved cross-platform compatibility\n\n## Security Features\n\n- **Random Skewing**: Each digit rotated -15\u00b0 to +15\u00b0\n- **Size Variation**: Random scaling 0.8x to 1.2x per digit\n- **Wave Distortion**: Sinusoidal distortion across the image\n- **Noise Patterns**: Curved lines and random dots\n- **Color Randomization**: Multiple predefined color schemes\n- **Millisecond Seeding**: High-precision random generation\n\n## Requirements\n\n- Python 3.7+\n- Pillow >= 8.0.0\n- importlib_resources >= 1.3.0 (for Python < 3.9)\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nIssues and pull requests are welcome on [GitHub](https://github.com/COD332/light-captcha).\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight CAPTCHA generator for Persian and English digits",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/COD332/light-captcha",
"Issues": "https://github.com/COD332/light-captcha/issues",
"Repository": "https://github.com/COD332/light-captcha"
},
"split_keywords": [
"captcha",
" persian",
" english",
" security",
" image",
" generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ac6812b08e07c3eeb5e8f21f5ebecb20649de78b50a5da05a578404bb5262531",
"md5": "82409e1758e0f3a610a39a4de742071e",
"sha256": "2452f3fea1a755a635c3c2a2df29992e071db31f6ff2f5e894e37fcdcd7b8a32"
},
"downloads": -1,
"filename": "light_captcha-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82409e1758e0f3a610a39a4de742071e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 113686,
"upload_time": "2025-08-03T05:50:15",
"upload_time_iso_8601": "2025-08-03T05:50:15.961816Z",
"url": "https://files.pythonhosted.org/packages/ac/68/12b08e07c3eeb5e8f21f5ebecb20649de78b50a5da05a578404bb5262531/light_captcha-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "21325474e9af6776af6035db597463a848042a3bf90e0b39ff3d0c64e628dd3a",
"md5": "bac840148c5ebb062f82dd649f71ea60",
"sha256": "a2e5ad8fee9a571c787175086a53d22ba5d2a07790ba86e44648db9c5cb10808"
},
"downloads": -1,
"filename": "light_captcha-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "bac840148c5ebb062f82dd649f71ea60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 116555,
"upload_time": "2025-08-03T05:50:17",
"upload_time_iso_8601": "2025-08-03T05:50:17.688169Z",
"url": "https://files.pythonhosted.org/packages/21/32/5474e9af6776af6035db597463a848042a3bf90e0b39ff3d0c64e628dd3a/light_captcha-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 05:50:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "COD332",
"github_project": "light-captcha",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "light-captcha"
}
JSON
