asciimatics
A cross platform package to do curses-like operations, plus higher level APIs and widgets to create text UIs and ASCII art animations
Top Related Projects
Quick Overview
Asciimatics is a Python library for creating text-based user interfaces and animations in the terminal. It provides a high-level API for creating complex, colorful, and interactive ASCII art animations and games, supporting both Windows and Unix-like systems.
Pros
- Cross-platform compatibility (Windows, Linux, macOS)
- Rich set of features for creating ASCII animations and text UIs
- Supports both simple and complex terminal-based applications
- Active development and community support
Cons
- Learning curve for more advanced features
- Limited to terminal-based applications
- May have performance issues with very complex animations
- Some features may not work consistently across all terminal types
Code Examples
- Creating a simple animation:
from asciimatics.screen import Screen
from asciimatics.effects import Cycle, Stars
from asciimatics.renderers import FigletText
from asciimatics.scene import Scene
def demo(screen):
effects = [
Cycle(
screen,
FigletText("ASCIIMATICS", font='big'),
int(screen.height / 2 - 8)),
Stars(screen, 200)
]
screen.play([Scene(effects, 500)])
Screen.wrapper(demo)
- Creating a basic form:
from asciimatics.widgets import Frame, TextBox, Layout, Label, Divider, Text, Button
from asciimatics.scene import Scene
from asciimatics.screen import Screen
from asciimatics.exceptions import ResizeScreenError
import sys
class ContactForm(Frame):
def __init__(self, screen):
super(ContactForm, self).__init__(screen,
int(screen.height * 2 // 3),
int(screen.width * 2 // 3),
hover_focus=True,
title="Contact Form")
layout = Layout([100])
self.add_layout(layout)
layout.add_widget(Label("Please enter your details:"))
layout.add_widget(TextBox(1, "Name:"))
layout.add_widget(TextBox(1, "Email:"))
layout.add_widget(TextBox(3, "Message:"))
layout.add_widget(Divider())
layout2 = Layout([1, 1, 1, 1])
self.add_layout(layout2)
layout2.add_widget(Button("Submit", self._submit), 3)
self.fix()
def _submit(self):
self.save()
raise NextScene("Main")
def demo(screen, scene):
scenes = [
Scene([ContactForm(screen)], -1, name="Main")
]
screen.play(scenes, stop_on_resize=True, start_scene=scene, allow_int=True)
last_scene = None
while True:
try:
Screen.wrapper(demo, catch_interrupt=True, arguments=[last_scene])
sys.exit(0)
except ResizeScreenError as e:
last_scene = e.scene
Getting Started
To get started with Asciimatics, first install it using pip:
pip install asciimatics
Then, you can create a simple animation like this:
from asciimatics.screen import Screen
from asciimatics.scene import Scene
from asciimatics.effects import Cycle
from asciimatics.renderers import FigletText
def demo(screen):
effects = [
Cycle(
screen,
FigletText("Hello, Asciimatics!", font='big'),
int(screen.height / 2 - 8))
]
screen.play([Scene(effects, 500)])
Screen.wrapper(demo)
Run this script to see a simple animation in your terminal.
Competitor Comparisons
Rich is a Python library for rich text and beautiful formatting in the terminal.
Pros of Rich
- More comprehensive text formatting and styling options
- Better support for tables, progress bars, and syntax highlighting
- Actively maintained with frequent updates and improvements
Cons of Rich
- Lacks animation capabilities
- No built-in support for interactive terminal applications
- Steeper learning curve for complex layouts
Code Comparison
Rich:
from rich import print
from rich.panel import Panel
print(Panel.fit("Hello, [bold magenta]World[/bold magenta]!"))
Asciimatics:
from asciimatics.screen import Screen
def demo(screen):
screen.print_at('Hello, World!', 0, 0)
screen.refresh()
screen.wait_for_input(10)
Screen.wrapper(demo)
Rich focuses on rich text formatting and output, while Asciimatics provides a framework for creating interactive terminal applications with animation support. Rich is better suited for enhancing command-line tool output, while Asciimatics excels in creating text-based user interfaces and games. The choice between the two depends on the specific requirements of your project.
🎨 ASCII art library for Python
Pros of art
- Simpler and more lightweight, focusing specifically on ASCII art generation
- Supports a wider range of ASCII art styles and fonts
- Easier to use for quick ASCII art creation without complex setup
Cons of art
- Less feature-rich compared to asciimatics' full-fledged terminal animation capabilities
- Limited to static ASCII art, lacking the dynamic and interactive elements of asciimatics
- No support for color or advanced terminal manipulations
Code Comparison
art:
from art import text2art
output = text2art("Hello")
print(output)
asciimatics:
from asciimatics.screen import Screen
from asciimatics.scene import Scene
from asciimatics.effects import Cycle, Stars
from asciimatics.renderers import FigletText
art is more straightforward for simple ASCII art generation, while asciimatics offers a more comprehensive set of tools for creating complex terminal animations and interfaces. art is better suited for quick ASCII art tasks, whereas asciimatics shines in creating rich, interactive terminal applications with animations and effects.
An implementation of figlet written in Python
Pros of pyfiglet
- Lightweight and focused solely on ASCII art text generation
- Easy to use with a simple API
- Supports a wide variety of fonts
Cons of pyfiglet
- Limited functionality compared to asciimatics
- Lacks advanced features like animations and color support
Code comparison
pyfiglet:
from pyfiglet import Figlet
f = Figlet(font='slant')
print(f.renderText('Hello, World!'))
asciimatics:
from asciimatics.renderers import FigletText
from asciimatics.screen import Screen
def demo(screen):
screen.print_at(FigletText("Hello, World!"), 1, 1)
screen.refresh()
screen.wait_for_input(10)
Screen.wrapper(demo)
Summary
pyfiglet is a simple and lightweight library focused on generating ASCII art text. It's easy to use and supports various fonts. However, it lacks the advanced features and versatility of asciimatics.
asciimatics, on the other hand, offers a more comprehensive set of tools for creating text-based interfaces and animations. It includes support for colors, effects, and complex layouts, making it suitable for more advanced terminal-based applications.
Choose pyfiglet for quick and simple ASCII art text generation, and asciimatics for more complex terminal-based user interfaces and animations.
Pixel graphics in terminal with unicode braille characters
Pros of drawille
- Lightweight and focused on drawing ASCII art and simple animations
- Easy to use for basic drawing tasks with minimal setup
- Supports Unicode Braille characters for higher resolution output
Cons of drawille
- Limited functionality compared to asciimatics' more comprehensive feature set
- Lacks advanced text formatting and color support
- No built-in support for complex animations or interactive applications
Code comparison
drawille example:
from drawille import Canvas
c = Canvas()
c.set(0, 0)
c.set(1, 1)
c.set(2, 2)
print(c.frame())
asciimatics example:
from asciimatics.screen import Screen
from asciimatics.scene import Scene
from asciimatics.effects import Cycle, Stars
from asciimatics.renderers import FigletText
Screen.wrapper(demo)
Summary
drawille is a simple and lightweight library for creating ASCII art and basic animations, while asciimatics offers a more comprehensive set of features for creating complex terminal-based user interfaces and animations. drawille is easier to use for simple drawing tasks, but asciimatics provides more advanced capabilities for interactive applications and rich text formatting.
Convert 
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
|status| |health| |coverage| |version| |chat|
.. |status| image:: https://github.com/peterbrittain/asciimatics/actions/workflows/test.yml/badge.svg :target: https://github.com/peterbrittain/asciimatics/actions/workflows/test.yml :alt: Build status
.. |health| image:: https://app.codacy.com/project/badge/Grade/c1fed1f2dc6a47a1bbe91f8851456beb :target: https://app.codacy.com/gh/peterbrittain/asciimatics/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade :alt: Code Health
.. |coverage| image:: https://codecov.io/gh/peterbrittain/asciimatics/graph/badge.svg?token=UlVFVeLagX :target: https://codecov.io/gh/peterbrittain/asciimatics :alt: Code Coverage
.. |version| image:: https://img.shields.io/pypi/v/asciimatics.svg :target: https://pypi.python.org/pypi/asciimatics :alt: Latest stable version
.. |chat| image:: https://badges.gitter.im/asciimatics/Lobby.svg :alt: Join the chat at https://gitter.im/asciimatics/Lobby :target: https://gitter.im/asciimatics/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
ASCIIMATICS
Asciimatics is a package to help people create full-screen text UIs (from interactive forms to ASCII animations) on any platform. It is licensed under the Apache Software Foundation License 2.0.
Why?
Why not? It brings a little joy to anyone who was programming in the 80s... Oh and it provides a single cross-platform Python class to do all the low-level console function you could ask for, including:
- Coloured/styled text - including 256 colour terminals and unicode characters (even CJK languages)
- Cursor positioning
- Keyboard input (without blocking or echoing) including unicode support
- Mouse input (terminal permitting)
- Detecting and handling when the console resizes
- Screen scraping
In addition, it provides some simple, high-level APIs to provide more complex features including:
- Anti-aliased ASCII line-drawing
- Image to ASCII conversion - including JPEG and GIF formats
- Many animation effects - e.g. sprites, particle systems, banners, etc.
- Various widgets for text UIs - e.g. buttons, text boxes, radio buttons, etc.
Currently this package has been proven to work on CentOS 6 & 7, Raspbian (i.e. Debian wheezy), Ubuntu 14.04, Windows 7, 8 & 10, OSX 10.11 and Android Marshmallow (courtesy of https://termux.com), though it should also work for any other platform that provides a working curses implementation.
It should be implementation agnostic and has been successfully tested on CPython and PyPy2.
(Please let me know if you successfully verified it on other platforms so that I can update this list).
Installation
Asciimatics supports Python version 3. For the precise list of tested versions,
refer to pypi <https://pypi.python.org/pypi/asciimatics>_. The last version of asciimatics
to support Python 2 is v1.14.
To install asciimatics, simply install with pip as follows:
.. code-block:: bash
$ pip install asciimatics
This should install all your dependencies for you. If you don't use pip or it fails to install
them, you can install the dependencies directly using the packages listed in requirements.txt <https://github.com/peterbrittain/asciimatics/blob/master/requirements.txt>_.
Additionally, Windows users (who aren't using pip) will need to install pywin32.
How to use it?
To use the low-level API, simply create a Screen and use it to print coloured text at any location, or get mouse/keyboard input. For example, here is a variant on the classic "hello world":
.. code-block:: python
from random import randint
from asciimatics.screen import Screen
def demo(screen):
while True:
screen.print_at('Hello world!',
randint(0, screen.width), randint(0, screen.height),
colour=randint(0, screen.colours - 1),
bg=randint(0, screen.colours - 1))
ev = screen.get_key()
if ev in (ord('Q'), ord('q')):
return
screen.refresh()
Screen.wrapper(demo)
That same code works on Windows, OSX and Linux and paves the way for all the higher level features. These still need the Screen, but now you also create a Scene using some Effects and then get the Screen to play it. For example, this code:
.. code-block:: python
from asciimatics.effects import Cycle, Stars
from asciimatics.renderers import FigletText
from asciimatics.scene import Scene
from asciimatics.screen import Screen
def demo(screen):
effects = [
Cycle(
screen,
FigletText("ASCIIMATICS", font='big'),
int(screen.height / 2 - 8)),
Cycle(
screen,
FigletText("ROCKS!", font='big'),
int(screen.height / 2 + 3)),
Stars(screen, 200)
]
screen.play([Scene(effects, 500)])
Screen.wrapper(demo)
should produce something like this:
.. image:: https://asciinema.org/a/18756.png :alt: asciicast :target: https://asciinema.org/a/18756?autoplay=1
Or maybe you're looking to create a TUI? In which case this
simple code <https://github.com/peterbrittain/asciimatics/blob/master/samples/contact_list.py>__
will give you this:
.. image:: https://asciinema.org/a/45946.png :alt: contact list sample :target: https://asciinema.org/a/45946?autoplay=1
Documentation
Full documentation of all the above (and more!) is available at http://asciimatics.readthedocs.org/
More examples
More examples of what you can do are available in the project samples directory, hosted on GitHub. See https://github.com/peterbrittain/asciimatics/tree/v1.15/samples.
To view them, simply download these files and then simply run them directly with python.
Alternatively, you can browse recordings of many of the samples in the gallery at
https://github.com/peterbrittain/asciimatics/wiki.
Bugs and enhancements
If you have a problem, please check out the troubleshooting guide at http://asciimatics.readthedocs.io/en/latest/troubleshooting.html. If this doesn't solve your problem, you can report bugs (or submit enhancement requests) at https://github.com/peterbrittain/asciimatics/issues.
Alternatively, if you just have some questions, feel free to drop in at https://gitter.im/asciimatics/Lobby.
Contributing to the project
If you'd like to take part in this project (and see your name in the credits!), check out the guidance at http://asciimatics.readthedocs.org/en/latest/contributing.html
Top Related Projects
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot