DisCapTy’s API#
Generator#
- class discapty.generators.Generator#
Base class for all generators.
A generator is used to especially generate a Captcha object based on a given text. A generator looks like this:
class MyGenerator(Generator): def generate(self, text: str) -> str: return "+".join(text)
A generator can be supplied with parameters using class’s attributes, for example:
class MyGenerator(Generator): separator = "+" def generate(self, text: str) -> str: return self.separator.join(text) gen1 = MyGenerator() # Separator here is "+" gen2 = MyGenerator(separator="-") # Separator here is "-"
Here, separator has a default value, which can be overridden by the user, or not. If you wish to create a generator with a required value, you can use “…”, like this:
class MyGenerator(Generator): separator: str = ... ... MyGenerator(separator="+") # Works! 👍 MyGenerator() # Raises an error! 👎
If you wish to know more on that subject, visit Pydantic’s documentation as this is what
Generator
uses under the hood. https://pydantic-docs.helpmanual.io/New in version 2.0.0.
- abstract generate(text: str) Any #
A method that needs to be implemented by the child class. This method will return the Captcha that the user has requested. For example:
class MyGenerator(Generator): def generate(self, text: str) -> str: return '+'.join(text)
- property optional_keys: List[str]#
Returns a list of all child’s optional keys.
- property required_keys: List[str]#
Returns a list of all child’s required keys.
Captcha#
- class discapty.Captcha(code: str, captcha_object: Any)#
Represent a Captcha object.
- property code: str#
The code in clear of the Captcha.
- property captcha: Any#
The captcha object. This is what’s send to the user.
- property type: Any#
The type of the captcha object. It is the same as doing
type(self.captcha)
.
Changed in version 2.0.0: The Captcha object is no longer what creates the Captcha image, it just is the representation of the Captcha that the user will face.
Challenge#
- class discapty.Challenge(generator: discapty.generators.Generator, challenge_id: Optional[str] = None, *, allowed_retries: Optional[int] = None, code: Optional[str] = None, code_length: Optional[int] = None)#
Representation of a challenge. A challenge represent the user’s Captcha question-answer he must face.
- This class takes cares of:
Generating the captcha
Verify inputs
Manage the “Captcha” object
It frees your mind from managing all the process of a captcha challenge, keeping your code short and easy.
- Parameters
generator (Generator) – The generator class to use. You cannot uses
discapty.generators.Generator
directly, you must subclass it and implement the “generate” function first.challenge_id (Optional[int | str]) – The id of the challenge. Can be a string or an id. If none is supplied, a random UUID will be generated.
retries (Optional[int]) – The number of retries allowed. Defaults to 3.
code (Optional[str]) – The code to use. If none is supplied, a random code will be generated.
code_length (int) – The length of the code to generate if no code is supplied. Defaults to 4.
New in version 2.0.0.
- begin() Any #
Start the challenge.
- Returns
The Captcha object to send to the user.
- Return type
- Raises
AlreadyCompletedError – If the challenge has already been completed. You cannot start a challenge twice, you need to create a new one.
AlreadyRunningError – If the challenge is already running.
TooManyRetriesError – If the number of failures is greater than the number of retries allowed. In other words, the challenge has failed.
- cancel() None #
Cancel the challenge.
- property captcha: discapty.captcha.Captcha#
Returns the Captcha class associated to this challenge.
- property captcha_object: Any#
Get the Captcha object.
- Returns
The Captcha object.
- Return type
typing.Any
- check(answer: str, *, force_casing: bool = False, remove_space: bool = True) bool #
Check an answer. This will always add +1 to attempted_tries and failures if necessary.
- Parameters
answer (str) – The answer to check against the Captcha’s code.
force_casing (bool) – If True, the casing must be respected.
remove_space (bool) – If True, spaces will be removed when checking the answer.
- Returns
True if the answer is correct, False otherwise.
- Return type
bool
- Raises
TooManyRetriesError – If the number of failures is greater than the number of retries allowed. We are still adding +1 to the failure even when raising the exception.
TypeError – The challenge cannot be edited (State is either not PENDING or not WAITING)
- property is_completed: bool#
Check if the challenge has been completed or failed.
- property is_correct: Optional[bool]#
Check if the challenge has been completed. If not, return None. If failed, return False.
- property is_wrong: Optional[bool]#
Check if the challenge has been failed. If not, return None. If completed, return False.
- reload(*, increase_attempted_tries=True, increase_failures=False) Any #
Reload the Challenge and its code.
This method will create a new random code. It will also increase the attempted_tries counter if requested. By defaults, this behavior is executed.
- Parameters
increase_attempted_tries (bool) – If True, the attempted_tries counter will be increased.
- Raises
TypeError – If the challenge cannot be edited or is not already running.
CaptchaQueue#
- class discapty.CaptchaQueue(generators: Union[discapty.generators.Generator, List[discapty.generators.Generator]], *, queue: Optional[Dict[str, discapty.challenge.Challenge]] = None)#
A safe handler for taking cares of managing the challenges for the developer.
It basically offers a sane & internal way to manage your captcha using a key-value pair without ever having to touch the challenges/captcha directly.
- Parameters
generators (Generator | List[Generator]) –
A list or a single generator to use for creating the challenges. If a list is given, a random generator will be picked up when using create_challenge.
You should be aware that inconsistency will occur this way, as if one generator can return a specific type and another one could return another kind of type.
queue (Optional[Dict[int, Challenge]]) – Import an existing queue. Shouldn’t be required.
- Raises
ValueError – If no generators has been passed.
- create_challenge(challenge_id: Optional[str] = None, *, retries: Optional[int] = None, code: Optional[str] = None, code_length: Optional[int] = None) discapty.challenge.Challenge #
Create a challenge for an id. Overwrite the challenge created before, unless the challenge is not fully completed.
- Parameters
challenge_id (str) – The id associated to the challenge. If not given, a random id will be generated.
retries (int) – The number of allowed retries. Defaults to 3.
code (str) – The code to use. Defaults to a random code.
code_length (int) – The length of the code to generate if no code is supplied. Defaults to 4.
- Returns
The generated challenge.
- Return type
- delete_challenge(challenge_id: str) None #
Delete a challenge of an id, if it exist.
- Parameters
challenge_id (int) – The id associated to the challenge.
- Raises
UnexistingChallengeError – If the given id does not have any associated challenge.
- get_challenge(challenge_id: str) discapty.challenge.Challenge #
Get the challenge of an id, if it exist.
- Parameters
challenge_id (str) – The id associated to the challenge.
- Returns
The challenge associated to the id.
- Return type
- Raises
UnexistingChallengeError – If the given id does not have any associated challenge.
States#
States are only used with discapty.Challenge
.
- class discapty.States(value)#
An enum representing the different states of a challenge.
Available states are:
PENDING : The challenge is waiting to begin.
WAITING : The challenge is waiting for user’s input.
COMPLETED : The challenge has been completed.
FAILED : The challenge has been failed without trouble.
FAILURE : The challenge has been completed without user’s input and in an unexpected way. (e.g. manually cancelled)
Errors#
- exception discapty.errors.AlreadyCompletedError#
Raised when a challenge has already been completed.
- exception discapty.errors.AlreadyRunningError#
Raised when a challenge is already running.
- exception discapty.errors.ChallengeCompletionError#
Raised when a challenge has an issue regarding it’s completion.
- exception discapty.errors.InvalidFontError#
Raised when one or more fonts are invalid.
- exception discapty.errors.NonexistingChallengeError#
Raised when trying to get a challenge that does not exist. Subclass of “KeyError” as this error will appear when trying to get the challenge from a dict.
- exception discapty.errors.TooManyRetriesError#
Raised when a challenge received more retries than allowed.