Metadata-Version: 2.4
Name: bengali-captcha
Version: 0.1.2
Summary: Six original Bengali CAPTCHA web variants with bundled fonts, backgrounds, and shape noise
License-Expression: MIT
Keywords: bengali,bangla,captcha,pillow,image
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Bengali
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: licenses/CLAPTCHA.txt
Requires-Dist: Pillow>=10.1
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6; extra == "release"
Dynamic: license-file

# Bengali CAPTCHA

**The first Bengali text-based CAPTCHA library, designed for easy integration into applications.**

bengali-captcha is a Pillow-based library for generating image CAPTCHAs using Bengali letters and digits—the first of its kind for the Bengali language. Developed from the research implementation presented in A Usable and Secure Bengali CAPTCHA[NMI Shibbir et al, Computers and Security 2024], it offers six rendering variants through a simple Python API, with output as Pillow images, in-memory streams, or image files. The accompanying study demonstrated the CAPTCHA designs’ usability and resistance to the automated attacks evaluated.

**The PyPI package includes the original Bengali fonts and background images.**
Installing it with `pip` installs those assets too. All six CAPTCHA variants
select their bundled assets automatically: no font path, background path,
separate download, or configuration is required.

The project is associated with the research paper
[**A Usable and Secure Bengali CAPTCHA**](https://arxiv.org/abs/2606.29077).
If you use this library in your research, please cite the paper using the
BibTeX entry in the **Citation** section below.


## Sample CAPTCHA

![Sample Bengali CAPTCHA](https://raw.githubusercontent.com/neyamul-sbr/ArtifactsBengaliCAPTCHA/d69a0ddd4d0f2cf5d8297db4d141bc1b5fd76f43/ben_captcha.png)

## Features

- Six rendering variants with automatically selected fonts and backgrounds.
- Bundled assets for offline generation after installation.
- Random Bengali challenge text generated using Python's `secrets` module.
- Custom challenge text, text-source callables, and configurable random-text length.
- Adjustable image size, margins, noise, and output format.
- Optional custom fonts, backgrounds, and supported text colors.
- Pillow image, in-memory stream, and file output.
- Command-line interface and a Django integration example.

## Installation

Requires **Python 3.10 or newer**.

```console
python -m pip install bengali-captcha
```

## Quick start

The original Bengali fonts and background images are included. Generate a
CAPTCHA immediately, with no font downloads or custom image paths:

```python
from bengali_captcha import BengaliCaptcha

captcha = BengaliCaptcha()
answer, image = captcha.image
image.save("captcha.png")
```

All six variants work out of the box:

```python
for variant in range(1, 7):
    answer, path = BengaliCaptcha(variant=variant).write(f"captcha-{variant}.png")
```

Default challenge lengths match the original site: 3-4 characters for variants
1, 3 and 5, and 3-5 for variants 2, 4 and 6. Challenge text uses the original
Bengali alphabet and digit selection with `secrets` randomness.
Pass `length=5` to change the length, or supply a string or callable as `source`.

To generate a longer random challenge:

```python
captcha = BengaliCaptcha(length=5)
answer, image = captcha.image
image.save("captcha.png")
```

## Output options

| API | Returns |
| --- | --- |
| `captcha.image` | `(answer, image)`, where `image` is a Pillow image |
| `captcha.bytes` | `(answer, stream)`, where `stream` is a `BytesIO` object positioned at the beginning |
| `captcha.write("captcha.png")` | `(answer, path)`, after writing a newly generated image to disk |

Generate image bytes using the included assets:

```python
captcha = BengaliCaptcha(variant=2, source="কখ১২")
answer, stream = captcha.bytes  # BytesIO, positioned at the beginning
png_data = stream.getvalue()
```

To generate and save directly to a file:

```python
answer, path = captcha.write("captcha.png")
```

**Each access to `.image`, `.bytes`, or `.write()` creates a new image and calls
the text source again.** Keep the answer returned by the same call as the image
you display. To save that exact image, use its `.save()` method as shown in the
quick start.


## Command-line usage

```console
bengali-captcha captcha.png
bengali-captcha captcha.png --variant 1 --length 4
python -m bengali_captcha captcha.png --variant 6
```

These commands use the included fonts and images. The only filename required
is where to save the generated PNG. The command prints its answer in UTF-8.

## Django integration

Generate bytes for each request and keep the corresponding answer in the
user's session. For example, inside a Django view:

```python
from django.http import HttpResponse
from bengali_captcha import BengaliCaptcha


def captcha_image(request):
    answer, stream = BengaliCaptcha().bytes
    request.session["captcha_answer"] = answer
    response = HttpResponse(stream.getvalue(), content_type="image/png")
    response["Cache-Control"] = "no-store"
    return response
```

Your form-processing view must validate the submitted answer against the stored
value and enforce challenge expiration, one-time use, and rate limiting. Keep
the answer on the server; the image response should contain only the image.

## Optional: use your own font or background

Skip this section to use the original CAPTCHA styles. Supply `font` or
`background` only when you want to replace a bundled asset; each override is
independent, so the asset you do not override keeps its bundled default.

```python
from bengali_captcha import BengaliCaptcha

# Optional custom font; the background still comes from the package.
captcha = BengaliCaptcha(variant=2, font="my-bengali-font.ttf")

# Optional custom background; the font still comes from the package.
captcha = BengaliCaptcha(variant=2, background="my-background.png")

# Optional: replace both assets.
captcha = BengaliCaptcha(
    variant=2,
    font="my-bengali-font.ttf",
    background="my-background.png",
)
answer, image = captcha.image
```

Custom fonts must support Bengali characters. A custom font path or Pillow
font object works with every variant. Custom backgrounds apply to variants
1, 2, 3, 4 and 5. Omitting either argument or passing `None` uses its bundled
default; `background=False` selects a white canvas.

The command line also accepts optional overrides:

```console
bengali-captcha captcha.png --variant 2 --font my-bengali-font.ttf --background my-background.png
```


## Citation

If you use **Bengali CAPTCHA** in your research, experiments, or academic
publications, please cite the following paper:

Md Neyamul Islam Shibbir, Md Hasibur Rahman, Farida Chowdhury, and Md Sadek
Ferdous. **A Usable and Secure Bengali CAPTCHA.** arXiv preprint
arXiv:2606.29077, 2026.

[Read the paper on arXiv](https://arxiv.org/abs/2606.29077).

```bibtex
@article{shibbir2026usable,
  title={A Usable and Secure Bengali CAPTCHA},
  author={Shibbir, Md Neyamul Islam and Rahman, Md Hasibur and Chowdhury, Farida and Ferdous, Md Sadek},
  journal={arXiv preprint arXiv:2606.29077},
  year={2026}
}
```

## Development and publishing

From the repository root, install the package in editable mode:

```console
python -m pip install -e .
```

Install the release tools, run the tests, build the distributions, and check
the package metadata:

```console
python -m pip install -e ".[release]"
python -m unittest discover -s tests -v
python -m build
python -m twine check --strict dist/*
```

## Acknowledgements

The generators are loosely derived from
[Claptcha by Piotr Kuszaj](https://github.com/kuszaj/claptcha).
Bengali-specific variant changes originate in the `captchaWeb` research application.

## License and credits

MIT License

Copyright (c) 2026 Md Neyamul Islam Shibbir, Md Hasibur Rahman, Md Sadek Ferdous, Farida Chowdhury

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.
