asciimatics

library1.15.0pypypi✓ verified 85d ago

A cross-platform package to replace curses (mouse/keyboard input & text colours/positioning) and create ASCII animations. Current version 1.15.0, requires Python >= 3.8. Releases are semi-regular, roughly every 6-12 months.

serialization

pip install asciimatics

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ASCIIMATICS

asciimatics

serializationpythonv1.15.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Screen

✓ from asciimatics.screen import Screen

✗ from asciimatics import Screen

Screen is in the screen subpackage, not at top level

Frame

✓ from asciimatics.widgets import Frame

✗ from asciimatics import Frame

Frame is in widgets subpackage since 1.13.0

Scene

✓ from asciimatics.scene import Scene

✗ from asciimatics import Scene

Scene is in the scene subpackage

Effect

✓ from asciimatics.effects import Effect, ...

✗ from asciimatics import Effect

Effects are in the effects subpackage

Sprite

✓ from asciimatics.sprites import Sprite

✗ from asciimatics import Sprite

Sprites are in the sprites subpackage

Label, Button, Text, Layout

✓ from asciimatics.widgets import Label, Button, Text, Layout

✗ from asciimatics import Label

All widgets are in the widgets subpackage since 1.13.0

Simple hello world using FigletText. Run with Python; creates a full-screen animation.

# Demo: bouncing ball animation import os from asciimatics.screen import Screen from asciimatics.scene import Scene from asciimatics.effects import Effect from asciimatics.renderers import FigletText def demo(screen): renderer = FigletText("Hello") effects = [ Effect(screen, 0, 0, renderer, delete=False) ] scene = Scene(effects, -1, name="Hello") screen.play([scene], stop_on_resize=True) Screen.wrapper(demo)

Debug

Known issues

breakingAsciimatics 1.15.0 drops Python 2 and requires Python >= 3.8. Python 3.9+ recommended.

fix

Upgrade to Python 3.8+ and asciimatics 1.15.0+.

affects: <1.15.0

breakingIn 1.14.0, Frame borders and scroll bars changed: Frame now supports scroll bars without borders. To have no border and no scroll bar, use Frame(has_border=False, can_scroll=False) explicitly.

fix

If you used Frame with has_border=False and expected no scroll bar, add can_scroll=False.

affects: >=1.14.0

breakingIn 1.9.0, screen became a mandatory positional parameter for all Effect constructors. Custom effects must pass screen to parent class.

fix

Update custom Effect __init__ to accept and pass screen parameter.

affects: >=1.9.0

deprecatedThe old top-level import `from asciimatics import Screen` is deprecated since 1.13.0. Use `from asciimatics.screen import Screen`.

fix

Update imports as per correct paths above.

affects: >=1.13.0

gotchaWhen using threads, Screen is not thread-safe. Do not call screen methods from multiple threads.

fix

Use Screen.wrapper() or manage screen access from a single thread.

affects: *

gotchaOn Windows, asciimatics may not handle mouse events without the pynput library. Install pynput or use keyboard only.

fix

pip install pynput for mouse support on Windows.

affects: *

Errors

Common errors & fixes

AttributeError: module 'asciimatics' has no attribute 'Screen'

Incorrect import path: `from asciimatics import Screen`.

fix

Use `from asciimatics.screen import Screen`.

ModuleNotFoundError: No module named 'asciimatics.screen'

Old version of asciimatics (<1.13.0) where widgets were not yet a subpackage, OR missing parentheses in import with Python 3.

fix

Update to latest version: pip install --upgrade asciimatics.

TypeError: __init__() missing 1 required positional argument: 'screen'

Custom Effect not passing screen to parent class. Since 1.9.0, screen is mandatory for Effect.

fix

Ensure custom Effect __init__ calls super().__init__(screen, *args, **kwargs) and passes screen parameter.

Termux: 'os' has no attribute 'kill' / screen_width not found

Asciimatics does not fully support Android/Termux without extra terminal emulation.

fix

Use a different terminal or run on desktop OS (Linux, macOS, Windows).

Upgrade

Version history

1.15.0latest on PyPI · released Oct 25, 2023

Audit

Dependencies

PillowoptionalImage conversion and sprite loading

pynputoptionalMouse handling on some platforms (optional)

winitAPIoptionalWindows console API (optional, Windows only)

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/peterbrittain/asciimatics ↗

packagehttps://pypi.org/project/asciimatics/ ↗

homepagehttps://asciimatics.readthedocs.io ↗