manim-captcha 1.0.0__tar.gz

manim_captcha-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose
+
+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.

manim_captcha-1.0.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: manim-captcha
+Version: 1.0.0
+Summary: Animated visual captcha generation library using Manim.
+Author: Jose Miguel Rios Rubio
+License: MIT
+Keywords: captcha,manim,animation,video,gif,mp4
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: manim==0.19.2
+Dynamic: license-file
+
+# Manim-Captcha
+
+<div style="display: flex;">
+  <img src="https://github.com/user-attachments/assets/62677f79-c7a3-49ad-b01a-0143e48cb7ae" alt="captcha_circle" width="270" />
+  <img src="https://github.com/user-attachments/assets/223b7e2d-99c4-410e-ab6e-4966ad47d2e8" alt="captcha_matrix" width="270" />
+  <img src="https://github.com/user-attachments/assets/3c606acd-24bf-45bf-8a45-6127f392ea73" alt="captcha_piramid" width="270" />
+</div>
+
+## Overview
+
+Animated visual captcha generation library using [Manim Framework](https://github.com/ManimCommunity/manim).
+
+Traditional CAPTCHAs are static images. Manim-Captcha generates animated visual challenges (e.g., moving selectors, distributed numbers, dynamic noise).
+
+This library offers:
+
+- A "Captcha Generator" that allows to request generation of captcha files.
+- A "Captcha Automatic Generator" for async operation that acts as a background process to automatically generate captcha files in the filesystem for a custom interval and keeping a maximum number of captchas files (file rotation).
+- Some builtin captchas animations that you can select to use.
+- Kind of "plugin" based system were you can provide any external custom Manim captcha animation script (scene) and make the library use it.
+- Easy way to pass custom properties to the captcha scenes for customization (like scenes).
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Library Development](#library-development)
+
+## Requirements
+
+The manim-captcha library requires python 3 (tested with v3.12), Manim Community framework, and the corresponding requirements for Manim (like Cairo and Pango libraries).
+
+## Installation
+
+**Note:** The next installation instructions are for Debian based Linux systems.
+
+From a command line, install the different requirements:
+
+```bash
+sudo apt-get update
+sudo apt-get install build-essential make python3 python3-dev python3-pip
+sudo apt-get install libcairo2-dev libpango1.0-dev
+```
+
+The library has been published to pypi so can be easily installed via pip:
+
+```bash
+pip install manim-captcha
+```
+
+## Usage
+
+Basic captcha generator:
+
+```python
+from manim_captcha.generator import CaptchaGenerator
+from manim_captcha.scenes import CaptchaScene
+from pathlib import Path
+
+generator = CaptchaGenerator()
+
+captcha = generator.generate(
+    code="1234",
+    scene=CaptchaScene.CIRCLE_NUMS,
+    out_dir=Path("./captchas"),
+    properties={
+        "theme": "dark",
+        "noise": True
+    }
+)
+
+if captcha.error:
+    print("Fail to create the captcha:")
+    print(captcha.error_info)
+else:
+    print("Captcha successfully created")
+    print(f"  Code: \"{captcha.code}\"")
+    print(f"  File: {captcha.file}")
+print("")
+```
+
+Async and non-blocking automatic captcha generator:
+
+```python
+import asyncio
+import logging
+from manim_captcha.auto_generator import CaptchaAutoGenerator
+from pathlib import Path
+
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    level=logging.INFO
+)
+logger = logging.getLogger(__name__)
+
+async def main():
+    # Setup the CaptchaAutoGenerator
+    MAX_NUM_CAPTCHAS = 5
+    TIME_GEN_INTERVAL_S = 10
+    OUT_DIR = Path("./captchas")
+    auto_generator = CaptchaAutoGenerator(
+        OUT_DIR, TIME_GEN_INTERVAL_S, MAX_NUM_CAPTCHAS)
+    # Start the generator process
+    start_success = await auto_generator.start()
+    if not start_success:
+        logger.error("Fail to Start CaptchaAutoGenerator")
+        return
+    # Wait and get some captchas during 1 minute
+    TIME_CHECK = 60
+    time_pass_s = 0
+    run = True
+    while run:
+        # Show number of captchas availables
+        num_captchas = auto_generator.num_captchas()
+        logger.info("Num Captchas Availables: %d", num_captchas)
+        # Try to get a captcha
+        captcha = auto_generator.get_captcha()
+        if not captcha.error:
+            logger.info("Captcha retrieved:")
+            logger.info("  Code: \"%s\"", captcha.code)
+            logger.info("  File: %s", str(captcha.file))
+        await asyncio.sleep(TIME_GEN_INTERVAL_S)
+        # Check if check end time has arrive to exit the loop
+        time_pass_s = time_pass_s + TIME_GEN_INTERVAL_S
+        if time_pass_s >= TIME_CHECK:
+            run = False
+    # Stop the generator process
+    await auto_generator.stop()
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+**Note:** You can find some extra usages in the *examples/* directory.
+
+## Library Development
+
+For library development, to ease project setup and installation of all the requirements, a Makefile and some bash scripts are provided for Linux systems based on Debian.
+
+Setup the project (this will install all system requirements and creates a python virtual environment):
+
+```bash
+make setup
+```
+
+Extra actions can be performed through make, just run make without argments to see the usage help:
+
+```bash
+make
+
+Usage:
+  setup: Setup Project and install requirements
+  test: Run project tests
+  check_code_style: Run Code Style Checks
+  check_static_types: Run Static Types Checks
+  install: Install local package in edit mode
+  publish: Publish the library to pypi
+```
+
+Now open any code editor (i.e. vscode) withing the python environment and start coding!

manim_captcha-1.0.0/README.md

@@ -0,0 +1,161 @@
+# Manim-Captcha
+
+<div style="display: flex;">
+  <img src="https://github.com/user-attachments/assets/62677f79-c7a3-49ad-b01a-0143e48cb7ae" alt="captcha_circle" width="270" />
+  <img src="https://github.com/user-attachments/assets/223b7e2d-99c4-410e-ab6e-4966ad47d2e8" alt="captcha_matrix" width="270" />
+  <img src="https://github.com/user-attachments/assets/3c606acd-24bf-45bf-8a45-6127f392ea73" alt="captcha_piramid" width="270" />
+</div>
+
+## Overview
+
+Animated visual captcha generation library using [Manim Framework](https://github.com/ManimCommunity/manim).
+
+Traditional CAPTCHAs are static images. Manim-Captcha generates animated visual challenges (e.g., moving selectors, distributed numbers, dynamic noise).
+
+This library offers:
+
+- A "Captcha Generator" that allows to request generation of captcha files.
+- A "Captcha Automatic Generator" for async operation that acts as a background process to automatically generate captcha files in the filesystem for a custom interval and keeping a maximum number of captchas files (file rotation).
+- Some builtin captchas animations that you can select to use.
+- Kind of "plugin" based system were you can provide any external custom Manim captcha animation script (scene) and make the library use it.
+- Easy way to pass custom properties to the captcha scenes for customization (like scenes).
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Library Development](#library-development)
+
+## Requirements
+
+The manim-captcha library requires python 3 (tested with v3.12), Manim Community framework, and the corresponding requirements for Manim (like Cairo and Pango libraries).
+
+## Installation
+
+**Note:** The next installation instructions are for Debian based Linux systems.
+
+From a command line, install the different requirements:
+
+```bash
+sudo apt-get update
+sudo apt-get install build-essential make python3 python3-dev python3-pip
+sudo apt-get install libcairo2-dev libpango1.0-dev
+```
+
+The library has been published to pypi so can be easily installed via pip:
+
+```bash
+pip install manim-captcha
+```
+
+## Usage
+
+Basic captcha generator:
+
+```python
+from manim_captcha.generator import CaptchaGenerator
+from manim_captcha.scenes import CaptchaScene
+from pathlib import Path
+
+generator = CaptchaGenerator()
+
+captcha = generator.generate(
+    code="1234",
+    scene=CaptchaScene.CIRCLE_NUMS,
+    out_dir=Path("./captchas"),
+    properties={
+        "theme": "dark",
+        "noise": True
+    }
+)
+
+if captcha.error:
+    print("Fail to create the captcha:")
+    print(captcha.error_info)
+else:
+    print("Captcha successfully created")
+    print(f"  Code: \"{captcha.code}\"")
+    print(f"  File: {captcha.file}")
+print("")
+```
+
+Async and non-blocking automatic captcha generator:
+
+```python
+import asyncio
+import logging
+from manim_captcha.auto_generator import CaptchaAutoGenerator
+from pathlib import Path
+
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    level=logging.INFO
+)
+logger = logging.getLogger(__name__)
+
+async def main():
+    # Setup the CaptchaAutoGenerator
+    MAX_NUM_CAPTCHAS = 5
+    TIME_GEN_INTERVAL_S = 10
+    OUT_DIR = Path("./captchas")
+    auto_generator = CaptchaAutoGenerator(
+        OUT_DIR, TIME_GEN_INTERVAL_S, MAX_NUM_CAPTCHAS)
+    # Start the generator process
+    start_success = await auto_generator.start()
+    if not start_success:
+        logger.error("Fail to Start CaptchaAutoGenerator")
+        return
+    # Wait and get some captchas during 1 minute
+    TIME_CHECK = 60
+    time_pass_s = 0
+    run = True
+    while run:
+        # Show number of captchas availables
+        num_captchas = auto_generator.num_captchas()
+        logger.info("Num Captchas Availables: %d", num_captchas)
+        # Try to get a captcha
+        captcha = auto_generator.get_captcha()
+        if not captcha.error:
+            logger.info("Captcha retrieved:")
+            logger.info("  Code: \"%s\"", captcha.code)
+            logger.info("  File: %s", str(captcha.file))
+        await asyncio.sleep(TIME_GEN_INTERVAL_S)
+        # Check if check end time has arrive to exit the loop
+        time_pass_s = time_pass_s + TIME_GEN_INTERVAL_S
+        if time_pass_s >= TIME_CHECK:
+            run = False
+    # Stop the generator process
+    await auto_generator.stop()
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+**Note:** You can find some extra usages in the *examples/* directory.
+
+## Library Development
+
+For library development, to ease project setup and installation of all the requirements, a Makefile and some bash scripts are provided for Linux systems based on Debian.
+
+Setup the project (this will install all system requirements and creates a python virtual environment):
+
+```bash
+make setup
+```
+
+Extra actions can be performed through make, just run make without argments to see the usage help:
+
+```bash
+make
+
+Usage:
+  setup: Setup Project and install requirements
+  test: Run project tests
+  check_code_style: Run Code Style Checks
+  check_static_types: Run Static Types Checks
+  install: Install local package in edit mode
+  publish: Publish the library to pypi
+```
+
+Now open any code editor (i.e. vscode) withing the python environment and start coding!

manim_captcha-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "manim-captcha"
+version = "1.0.0"
+description = "Animated visual captcha generation library using Manim."
+authors = [
+    { name="Jose Miguel Rios Rubio" }
+]
+readme = "README.md"
+license = { text = "MIT" }
+keywords = ["captcha", "manim", "animation", "video", "gif", "mp4"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+requires-python = ">=3.12"
+dependencies = [
+    "manim==0.19.2"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

manim_captcha-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

manim_captcha-1.0.0/src/manim_captcha/auto_generator.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Script:
+    auto_generator.py
+Description:
+    Automatic captcha generation manager.
+    This component act as a producer that periodically creates and store
+    random Manim Captchas into a directory of the filesystem, allowing
+    external consumers (users of the library) to request any of these
+    captchas. It keeps control of the number of generated captchas, and
+    apply some kind of "files rotation" of the storage, removing and
+    replacing older captchas with newer ones to control and limit the
+    maximum number of captchas in the filesytem.
+Author:
+    Jose Miguel Rios Rubio
+Creation date:
+    15/02/2026
+Last modified date:
+    16/02/2026
+Version:
+    1.0.0
+"""
+
+###############################################################################
+# Standard Libraries
+###############################################################################
+
+import asyncio
+import logging
+import secrets
+
+from pathlib import Path
+from traceback import format_exc
+
+
+###############################################################################
+# Third-Party Libraries
+###############################################################################
+
+# None
+
+
+###############################################################################
+# Local Libraries
+###############################################################################
+
+from .data import CaptchaData
+from .generator import CaptchaGenerator
+
+
+###############################################################################
+# Logger Setup
+###############################################################################
+
+logger = logging.getLogger(__name__)
+
+
+###############################################################################
+# Class ManimCaptchaGenerator
+###############################################################################
+
+class CaptchaAutoGenerator:
+    """Automatic captcha generation manager."""
+
+    ###########################################################################
+
+    ### Constants ###
+
+    # None
+
+    ###########################################################################
+
+    ### Data Types ###
+
+    # None
+
+    ###########################################################################
+
+    ### Constructor ###
+
+    def __init__(self,
+                 out_dir: Path = Path("./captchas"),
+                 interval_s: int = 60,
+                 max_items: int = 100):
+        '''
+        Automatic captcha generation manager construction.
+        Arguments:
+        - out_dir: Output directory to place the generated captchas.
+        - interval: Time for creation of each new Captcha (in seconds).
+        - max_items: Maximum number of Captchas allowed in the
+        filesystem (once this number of captchas are generated, the file
+        rotate mechanism will be replacing older captchas with newer
+        ones).
+        '''
+        self.out_dir = out_dir
+        self.interval_s = interval_s
+        self.max_items = max_items
+        self.format: str = "mp4"
+        self._task_create: asyncio.Task | None = None
+        self._task_remove: asyncio.Task | None = None
+        self._running: bool = False
+        self._lock = asyncio.Lock()
+        self._generator = CaptchaGenerator()
+        self.available: bool = self._generator.is_available()
+
+    ###########################################################################
+
+    ### Public Methods ###
+
+    async def start(self) -> bool:
+        '''Launch the manager to start creating captchas.'''
+        if not self.available:
+            return False
+        if self._running:
+            return False
+        self._running = True
+        self._task_create = asyncio.create_task(self._producer_loop())
+        self._task_remove = asyncio.create_task(self._remove_loop())
+        return True
+
+    async def stop(self):
+        '''Stop the manager and the captcha creation.'''
+        self._running = False
+        if self._task_create:
+            await self._task_create
+            self._task_create = None
+        if self._task_remove:
+            await self._task_remove
+            self._task_remove = None
+
+    def is_running(self) -> bool:
+        '''Get Captcha Generator manager running status.'''
+        return self._running
+
+    def num_captchas(self) -> int:
+        '''
+        Get the number of generated captcha files availables in the
+        file system.
+        '''
+        try:
+            return sum(1 for _ in self.out_dir.glob(f"*.{self.format}"))
+        except Exception:
+            logger.exception("Fail to get number of captchas files available")
+            return 0
+
+    def get_captcha(self) -> CaptchaData:
+        '''Return a random captcha file from storage.'''
+        captcha_result = CaptchaData()
+        if not self.available:
+            captcha_result.error = True
+            captcha_result.error_info = "Manim not found in the system"
+            return captcha_result
+        try:
+            files = list(self.out_dir.glob(f"*.{self.format}"))
+            if not files:
+                captcha_result.error = True
+                captcha_result.error_info = "None captcha files generated"
+                return captcha_result
+            captcha_result.file = secrets.choice(files)
+            captcha_result.code = captcha_result.file.stem
+        except Exception:
+            logger.error(format_exc())
+            captcha_result.error = True
+            captcha_result.error_info = "Fail to get captcha from filesystem"
+        return captcha_result
+
+    ###########################################################################
+
+    ### Private Methods - Create Captchas ###
+
+    async def _producer_loop(self):
+        """Internal async captcha creation producer loop."""
+        while self._running:
+            try:
+                async with self._lock:
+                    await self._generate_captcha()
+            except Exception:
+                logger.error(format_exc())
+            await asyncio.sleep(self.interval_s)
+
+    async def _generate_captcha(self):
+        """Generate a captcha."""
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(
+            None,
+            self._generator.generate,
+            None,  # code
+            None,  # scene
+            self.out_dir
+        )
+        if result.error:
+            logger.error("Captcha generation failed: %s", result.error_info)
+        else:
+            logger.debug("Generated captcha: %s", result.file)
+
+    ###########################################################################
+
+    ### Private Methods - Remove Captchas ###
+
+    async def _remove_loop(self):
+        """Internal async captcha remove/rotate loop."""
+        while self._running:
+            try:
+                async with self._lock:
+                    self._process_remove()
+            except Exception:
+                logger.error(format_exc())
+            await asyncio.sleep(self.interval_s)
+
+    def _process_remove(self):
+        """Remove oldest file if limit exceeded."""
+        # Dont remove if number of captchas is less than max_items limit
+        files = list(self.out_dir.glob(f"*.{self.format}"))
+        if len(files) < self.max_items:
+            return
+        # Remove oldest captcha file
+        files.sort(key=lambda p: p.stat().st_mtime)
+        while len(files) > self.max_items:
+            oldest = files.pop(0)
+            try:
+                # Atomic rename (protect race condition from consumers)
+                # and delete the file
+                deleting = oldest.with_suffix(oldest.suffix + ".deleting")
+                oldest.rename(deleting)
+                deleting.unlink(missing_ok=True)
+                logger.info("Removed old captcha: %s", oldest)
+            except PermissionError:
+                logger.warning("File in use, skipping removal: %s", oldest)
+            except Exception:
+                logger.error(format_exc())
+
+###############################################################################