Project

Bugs or suggestions? Visit the issue tracker and file an issue. We welcome your bug reports and feature suggestions!

Are you stuck and need support? Give stackoverflow a try. If you’re still having trouble, we’d like to hear about it! Open an issue in the issue tracker with a well-formed question.

Would you like to contribute? That’s awesome! Pull Requests are always welcome!

Fork

Blessed is a fork of blessings. Apologies for the fork, I just couldn’t get the Keyboard, and later Location or Measuring code accepted upstream after two major initiatives, the effort was better spent in a fork, where the code is accepted.

Furthermore, a project in the node.js language of the same name, blessed, is not related, or a fork of each other in any way.

License

Blessed is under the MIT License. See the LICENSE file. Please enjoy!

Running Tests

Install and run tox:

pip install --upgrade tox
tox

Py.test is used as the test runner, and with the tox target supporting positional arguments, you may for example use –looponfail, stopping at the first failing test case, and looping (retrying) after a filesystem save is detected:

tox -e py39 -- --looponfail --exitfirst

The test runner (tox) ensures all code and documentation complies with standard python style guides, pep8 and pep257, as well as various static analysis tools.

Warning

When you contribute a new feature, make sure it is covered by tests.

Likewise, some bug fixes should include a test demonstrating the bug.

Further Reading

As a developer’s API, blessed is often bundled with frameworks and toolsets that dive deeper into Terminal I/O programming than Terminal offers. Here are some recommended readings to help you along:

  • The terminfo(5) manpage of your preferred posix-like operating system. The capabilities available as attributes of Terminal are directly mapped to those listed in the column Cap-name.

  • The termios(3) of your preferred posix-like operating system.

  • The TTY demystified by Linus Åkesson.

  • A Brief Introduction to Termios by Nelson Elhage.

  • Richard Steven’s Advance Unix Programming (“AUP”) provides two very good chapters, “Terminal I/O” and “Pseudo Terminals”.

  • GNU’s The Termcap Manual by Richard M. Stallman.

  • Chapter 4 of CUNY’s course material for Introduction to System Programming, by Stewart Weiss

  • Chapter 11 of the IEEE Open Group Base Specifications Issue 7, “General Terminal Interface”

  • The GNU C Library documentation, section Low-Level Terminal Interface

  • The source code of many popular terminal emulators. If there is ever any question of “the meaning of a terminal capability”, or whether or not your preferred terminal emulator actually handles them, read the source! Many modern terminal emulators are now based on libvte.

  • The source code of the tty(4), pty(7), and the given “console driver” for any posix-like operating system. If you search thoroughly enough, you will eventually discover a terminal sequence decoder, usually a case switch that translates \x1b[0m into a “reset color” action towards the video driver. Though tty.c linked here is probably not the most interesting, it can get you started:

  • Thomas E. Dickey has been maintaining xterm, as well as a primary maintainer of many related packages such as ncurses for quite a long while. His consistent, well-documented, long-term dedication to xterm, curses, and the many related projects is world-renown.

  • termcap & terminfo (O’Reilly Nutshell) by Linda Mui, Tim O’Reilly, and John Strang.

  • Note that System-V systems, also known as Unix98 (SunOS, HP-UX, AIX and others) use a Streams interface. On these systems, the ioctl(2) interface provides the PUSH and POP parameters to communicate with a Streams device driver, which differs significantly from Linux and BSD.

    Many of these systems provide compatible interfaces for Linux, but they may not always be as complete as the counterpart they emulate, most especially in regards to managing pseudo-terminals.

The misnomer of ANSI

When people say ‘ANSI’, they are discussing:

  • Standard ECMA-48: Control Functions for Coded Character Sets

  • ANSI X3.64 from 1981, when the American National Standards Institute adopted the ECMA-48 as standard, which was later withdrawn in 1997 (so in this sense it is not an ANSI standard).

  • The ANSI.SYS driver provided in MS-DOS and clones. The popularity of the IBM Personal Computer and MS-DOS of the era, and its ability to display colored text further populated the idea that such text “is ANSI”.

  • The various code pages used in MS-DOS Personal Computers, providing “block art” characters in the 8th bit (int 127-255), paired with ECMA-48 sequences supported by the MS-DOS ANSI.SYS driver to create artwork, known as ANSI art.

  • The ANSI terminal database entry and its many descendants in the terminfo database. This is mostly due to terminals compatible with SCO UNIX, which was the successor of Microsoft’s Xenix, which brought some semblance of the Microsoft DOS ANSI.SYS driver capabilities.

  • Select Graphics Rendition (SGR) on vt100 clones, which include many of the common sequences in ECMA-48.

  • Any sequence started by the Control-Sequence-Inducer is often mistakenly termed as an “ANSI Escape Sequence” though not appearing in ECMA-48 or interpreted by the ANSI.SYS driver. The adjoining phrase “Escape Sequence” is so termed because it follows the ASCII character for the escape key (ESC, \x1b).