API References

Here are the list of API reference; it might be helpful for developers.

Image

class captcha.image.ImageCaptcha(width: int = 160, height: int = 60, fonts: list[str] | None = None, font_sizes: tuple[int, ...] | None = None)

Create an image CAPTCHA.

Many of the codes are borrowed from wheezy.captcha, with a modification for memory and developer friendly.

ImageCaptcha has one built-in font, DroidSansMono, which is licensed under Apache License 2. You should always use your own fonts:

captcha = ImageCaptcha(fonts=['/path/to/A.ttf', '/path/to/B.ttf'])

You can put as many fonts as you like. But be aware of your memory, all of the fonts are loaded into your memory, so keep them a lot, but not too many.

Parameters:

  • width – The width of the CAPTCHA image.

  • height – The height of the CAPTCHA image.

  • fonts – Fonts to be used to generate CAPTCHA images.

  • font_sizes – Random choose a font size from this parameters.

create_captcha_image(chars: str, color: Tuple[int, int, int] | Tuple[int, int, int, int], background: Tuple[int, int, int] | Tuple[int, int, int, int]) → Image

Create the CAPTCHA image itself.

Parameters:

  • chars – text to be generated.

  • color – color of the text.

  • background – color of the background.

The color should be a tuple of 3 numbers, such as (0, 255, 255).

generate(chars: str, format: str = 'png') → BytesIO

Generate an Image Captcha of the given characters.

Parameters:

  • chars – text to be generated.

  • format – image file format

generate_image(chars: str) → Image

Generate the image of the given characters.

Parameters:

chars – text to be generated.

write(chars: str, output: str, format: str = 'png') → None

Generate and write an image CAPTCHA data to the output.

Parameters:

  • chars – text to be generated.

  • output – output destination.

  • format – image file format

Audio

class captcha.audio.AudioCaptcha(voicedir: str | None = None)

Create an audio CAPTCHA.

Create an instance of AudioCaptcha is pretty simple:

captcha = AudioCaptcha()
captcha.write('1234', 'out.wav')

This module has a built-in digits CAPTCHA, but it is suggested that you create your own voice data library. A voice data library is a directory that contains lots of single charater named directories, for example:

voices/
    0/
    1/
    2/

The single charater named directories contain the wave files which pronunce the directory name. A charater directory can has many wave files, this AudioCaptcha will randomly choose one of them.

You should always use your own voice library:

captcha = AudioCaptcha(voicedir='/path/to/voices')
property choices: List[str]

Available choices for characters to be generated.

generate(chars: str) → bytearray

Generate audio CAPTCHA data. The return data is a bytearray.

Parameters:

chars – text to be generated.

load() → None

Load voice data into memory.

random(length: int = 6) → List[str]

Generate a random string with the given length.

Parameters:

length – the return string length.

write(chars: str, output: str) → None

Generate and write audio CAPTCHA data to the output.

Parameters:

  • chars – text to be generated.

  • output – output destionation.