/ Command-line Tools

A package to create full-screen text UIs

A package to create full-screen text UIs

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 the 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 versions 2 & 3. For the precise list of tested versions,
refer to pypi <https://pypi.python.org/pypi/asciimatics>_.

To install asciimatics, simply install with pip as follows:

    $ 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 pypiwin32.

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":

    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:

    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:

asciicast

Or maybe you're looking to create a TUI? In which case this simple code will give you this:

contact-list-sample

GitHub