{"id":3884,"library":"ascii-magic","title":"ASCII Magic","description":"ASCII Magic is a Python package (v2.7.4) that converts images into ASCII art for terminals and HTML. It provides functionalities to generate ASCII art from local image files, URLs, or Pillow image objects. The library is actively maintained, with several minor releases in late 2025 and early 2026 that introduced new features and addressed compatibility issues.","status":"active","version":"2.7.4","language":"en","source_language":"en","source_url":"https://github.com/LeandroBarone/python-ascii_magic","tags":["image processing","ascii art","terminal","html","image-to-text"],"install":[{"cmd":"pip install ascii-magic","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for image processing and handling various image formats.","package":"Pillow","optional":false},{"reason":"Recommended for enabling color output in older Windows terminals if colors do not display correctly. No longer a direct dependency since v2.4 for modern Windows.","package":"colorama","optional":true}],"imports":[{"note":"Since v2.0, the library was completely rewritten to be object-oriented. All core functionality is accessed via the `AsciiArt` class methods.","wrong":"import ascii_magic; ascii_magic.from_image(...)","symbol":"AsciiArt","correct":"from ascii_magic import AsciiArt"}],"quickstart":{"code":"import os\nfrom ascii_magic import AsciiArt\n\n# Create a dummy image file for demonstration\ndummy_image_path = \"dummy_image.png\"\nwith open(dummy_image_path, \"wb\") as f:\n    # A minimal (invalid) PNG header to simulate a file\n    f.write(b'\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\rIHDR\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x01\\x08\\x06\\x00\\x00\\x00\\x1f\\x15\\xc4\\x89\\x00\\x00\\x00\\x0cIDATx\\xda\\xed\\xc1\\x01\\x01\\x00\\x00\\x00\\xc2\\xa0\\xf7Om\\x00\\x00\\x00\\x00IEND\\xaeB`\\x82')\n\ntry:\n    # Create AsciiArt object from an image file\n    # Replace 'dummy_image.png' with your actual image path or a URL (AsciiArt.from_url)\n    my_art = AsciiArt.from_image(dummy_image_path)\n    \n    # Print the ASCII art to the terminal\n    my_art.to_terminal(columns=80)\n    \n    # Example of saving to an HTML file\n    my_art.to_html_file('output.html', columns=120, full_color=True)\n    print(\"ASCII art saved to output.html\")\n    \nexcept FileNotFoundError:\n    print(f\"Error: Image file '{dummy_image_path}' not found. Please provide a valid image path.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy image file\n    if os.path.exists(dummy_image_path):\n        os.remove(dummy_image_path)\n","lang":"python","description":"This quickstart demonstrates how to load an image from a local file and display its ASCII art representation in the terminal. It also shows how to export the ASCII art to an HTML file. Replace `dummy_image.png` with your desired image file."},"warnings":[{"fix":"Rewrite existing code to use the `AsciiArt` class and its methods (e.g., `AsciiArt.from_image()`, `my_art.to_terminal()`).","message":"Version 2.0 introduced a complete rewrite of the library, transitioning to a full object-oriented programming (OOP) model. Code written for 1.x versions is no longer compatible with 2.x and above.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate to newer integrated AI features like `from_gemini()` (v2.6) or `from_swarmui()` (v2.7), or handle image generation externally and pass a Pillow image object using `AsciiArt.from_pillow_image()`.","message":"Support for DALL-E, Stable Diffusion, and Craiyon APIs was removed in v2.6 and v2.4 due to API availability changes. Functions like `from_dalle()` and `from_stable_diffusion()` are no longer available.","severity":"deprecated","affected_versions":">=2.4.0, >=2.6.0"},{"fix":"Install `colorama` (`pip install colorama`) and call `colorama.init()` before printing ASCII art to the terminal: `import colorama; colorama.init(); my_art.to_terminal()`.","message":"On some Windows terminals, colors might not display correctly even if enabled. This is often due to the terminal's compatibility with ANSI escape codes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap calls to `from_url()` in a `try-except` block to gracefully handle potential `OSError` or `urllib.error.URLError` exceptions, informing the user about the issue.","message":"When using `AsciiArt.from_url()`, network or server issues can cause `urllib.error.URLError` (or a generic `OSError`) if the image cannot be fetched.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}