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
Raw data
{
"_id": null,
"home_page": "https://github.com/peterbrittain/asciimatics",
"name": "asciimatics",
"maintainer": "",
"docs_url": null,
"requires_python": ">= 3.8",
"maintainer_email": "",
"keywords": "ascii ansi art credits titles animation curses ncurses windows xterm mouse keyboard terminal tty color colour crossplatform console",
"author": "Peter Brittain",
"author_email": "peter.brittain.os@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dd/2e/146aca5e940c3b0df5c93c99e6eefe9c52e1e70a0e91fc98d2b466de61a4/asciimatics-1.15.0.tar.gz",
"platform": null,
"description": "ASCIIMATICS\n===========\n\nAsciimatics is a package to help people create full-screen text UIs (from interactive forms to\nASCII animations) on any platform. It is licensed under the Apache Software Foundation License 2.0.\n\nWhy?\n----\n\nWhy not? It brings a little joy to anyone who was programming in the 80s... Oh and it provides a\nsingle cross-platform Python class to do all the low-level console function you could ask for,\nincluding:\n\n* Coloured/styled text - including 256 colour terminals and unicode characters (even CJK languages)\n* Cursor positioning\n* Keyboard input (without blocking or echoing) including unicode support\n* Mouse input (terminal permitting)\n* Detecting and handling when the console resizes\n* Screen scraping\n\nIn addition, it provides some simple, high-level APIs to provide more complex features including:\n\n* Anti-aliased ASCII line-drawing\n* Image to ASCII conversion - including JPEG and GIF formats\n* Many animation effects - e.g. sprites, particle systems, banners, etc.\n* Various widgets for text UIs - e.g. buttons, text boxes, radio buttons, etc.\n\nCurrently this package has been proven to work on CentOS 6 & 7, Raspbian (i.e. Debian wheezy),\nUbuntu 14.04, Windows 7, 8 & 10, OSX 10.11 and Android Marshmallow (courtesy of https://termux.com),\nthough it should also work for any other platform that provides a working curses implementation.\n\nIt should be implementation agnostic and has been successfully tested on CPython and PyPy2.\n\n(Please let me know if you successfully verified it on other platforms so that I can update this\nlist).\n\nInstallation\n------------\n\nAsciimatics supports Python version 3. For the precise list of tested versions,\nrefer to `pypi <https://pypi.python.org/pypi/asciimatics>`_. The last version of asciimatics\nto support Python 2 is v1.14.\n\nTo install asciimatics, simply install with `pip` as follows:\n\n.. code-block:: bash\n\n $ pip install asciimatics\n\nThis should install all your dependencies for you. If you don't use pip or it fails to install\nthem, you can install the dependencies directly using the packages listed in `requirements.txt\n<https://github.com/peterbrittain/asciimatics/blob/master/requirements.txt>`_.\nAdditionally, Windows users (who aren't using `pip`) will need to install `pywin32`.\n\nHow to use it?\n--------------\nTo use the low-level API, simply create a Screen and use it to print coloured text at any location,\nor get mouse/keyboard input. For example, here is a variant on the classic \"hello world\":\n\n.. code-block:: python\n\n from random import randint\n from asciimatics.screen import Screen\n\n def demo(screen):\n while True:\n screen.print_at('Hello world!',\n randint(0, screen.width), randint(0, screen.height),\n colour=randint(0, screen.colours - 1),\n bg=randint(0, screen.colours - 1))\n ev = screen.get_key()\n if ev in (ord('Q'), ord('q')):\n return\n screen.refresh()\n\n Screen.wrapper(demo)\n\nThat same code works on Windows, OSX and Linux and paves the way for all the higher level features.\nThese still need the Screen, but now you also create a Scene using some Effects and then get the\nScreen to play it. For example, this code:\n\n.. code-block:: python\n\n from asciimatics.effects import Cycle, Stars\n from asciimatics.renderers import FigletText\n from asciimatics.scene import Scene\n from asciimatics.screen import Screen\n\n def demo(screen):\n effects = [\n Cycle(\n screen,\n FigletText(\"ASCIIMATICS\", font='big'),\n int(screen.height / 2 - 8)),\n Cycle(\n screen,\n FigletText(\"ROCKS!\", font='big'),\n int(screen.height / 2 + 3)),\n Stars(screen, 200)\n ]\n screen.play([Scene(effects, 500)])\n\n Screen.wrapper(demo)\n\nshould produce something like this:\n\n.. image:: https://asciinema.org/a/18756.png\n :alt: asciicast\n :target: https://asciinema.org/a/18756?autoplay=1\n\nOr maybe you're looking to create a TUI? In which case this\n`simple code <https://github.com/peterbrittain/asciimatics/blob/master/samples/contact_list.py>`__\nwill give you this:\n\n.. image:: https://asciinema.org/a/45946.png\n :alt: contact list sample\n :target: https://asciinema.org/a/45946?autoplay=1\n\nDocumentation\n-------------\n\nFull documentation of all the above (and more!) is available at http://asciimatics.readthedocs.org/\n\nMore examples\n-------------\n\nMore examples of what you can do are available in the project samples directory, hosted on GitHub.\nSee https://github.com/peterbrittain/asciimatics/tree/v1.15/samples.\n\nTo view them, simply download these files and then simply run them directly with `python`.\nAlternatively, you can browse recordings of many of the samples in the gallery at\nhttps://github.com/peterbrittain/asciimatics/wiki.\n\nBugs and enhancements\n---------------------\n\nIf you have a problem, please check out the troubleshooting guide at\nhttp://asciimatics.readthedocs.io/en/latest/troubleshooting.html. If this doesn't solve your\nproblem, you can report bugs (or submit enhancement requests) at\nhttps://github.com/peterbrittain/asciimatics/issues.\n\nAlternatively, if you just have some questions, feel free to drop in at\nhttps://gitter.im/asciimatics/Lobby.\n\nContributing to the project\n---------------------------\n\nIf you'd like to take part in this project (and see your name in the credits!), check out the\nguidance at http://asciimatics.readthedocs.org/en/latest/contributing.html\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A cross-platform package to replace curses (mouse/keyboard input & text colours/positioning) and create ASCII animations",
"version": "1.15.0",
"project_urls": {
"Homepage": "https://github.com/peterbrittain/asciimatics"
},
"split_keywords": [
"ascii",
"ansi",
"art",
"credits",
"titles",
"animation",
"curses",
"ncurses",
"windows",
"xterm",
"mouse",
"keyboard",
"terminal",
"tty",
"color",
"colour",
"crossplatform",
"console"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35bf9cad857b630c840738003eb24c1adb63490a1024ec40a9dcc3a753300c38",
"md5": "3e99d58eb67f3a502b0f9d8f93aff40d",
"sha256": "0fe068a6bed522929bd04bb5b8a2fb6ebf0aef1b7a9b3843cf71030a34bc38d5"
},
"downloads": -1,
"filename": "asciimatics-1.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e99d58eb67f3a502b0f9d8f93aff40d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">= 3.8",
"size": 137330,
"upload_time": "2023-10-25T15:19:05",
"upload_time_iso_8601": "2023-10-25T15:19:05.159454Z",
"url": "https://files.pythonhosted.org/packages/35/bf/9cad857b630c840738003eb24c1adb63490a1024ec40a9dcc3a753300c38/asciimatics-1.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dd2e146aca5e940c3b0df5c93c99e6eefe9c52e1e70a0e91fc98d2b466de61a4",
"md5": "4304a1cd34e8fa2080bae81a80f47fd7",
"sha256": "cfdd398042727519d8b73e62b8ef82c0becfed4eb420899c3b96c98d0b96821a"
},
"downloads": -1,
"filename": "asciimatics-1.15.0.tar.gz",
"has_sig": false,
"md5_digest": "4304a1cd34e8fa2080bae81a80f47fd7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">= 3.8",
"size": 2642946,
"upload_time": "2023-10-25T15:19:07",
"upload_time_iso_8601": "2023-10-25T15:19:07.211160Z",
"url": "https://files.pythonhosted.org/packages/dd/2e/146aca5e940c3b0df5c93c99e6eefe9c52e1e70a0e91fc98d2b466de61a4/asciimatics-1.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-25 15:19:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "peterbrittain",
"github_project": "asciimatics",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"landscape": true,
"requirements": [],
"lcname": "asciimatics"
}
JSON
