.. py:currentmodule:: blessed.terminal
Version History
===============
1.19
* introduced :meth:`~Terminal.truncate` to truncate a string while
retaining the sequences, :ghissue:`211` by :ghuser:`fishermans-friend`
* enhancement: Add small sleep in :meth:`~Terminal.kbhit` on Windows
to reduce CPU load :ghissue:`209` by :ghuser:`numerlor`
* enhancement: :meth:`~Terminal.rjust`, :meth:`~Terminal.ljust`,
and :meth:`~Terminal.center` now accept :class:`~typing.SupportsIndex` types, :ghissue:`234`
* enhancement: When 88 colors is detected, it is now interpreted as 16 colors rather than raising
an :exc:`AssertionError`, :ghissue:`235`
* bugfix: Fix global variable declarations in type annotations, :ghissue:`230` by
:ghuser:`mwchase`
1.18
* bugfix: :meth:`~Terminal.split_seqs` for some sequences
like ``term.move_left(3)``, :ghissue:`197`.
* introduced: type annotations, :ghissue:`192` by :ghuser:`dlax`.
* bugfix: do not fail when ``sys.stdin`` is unset, :ghissue:`195` by
:ghuser:`Olen`
* docfix: correct "Bottom of the screen" example to use ``end=''`` and
document about it in location.rst, :ghissue:`188` by :ghuser:`pyfisch`
1.17
* introduced: :ref:`hyperlinks`, method :meth:`~Terminal.link`, :ghissue:`116`.
* introduced: 24-bit color support, detected by ``term.number_of_colors == 1 << 24``, and 24-bit
color foreground method :meth:`~Terminal.color_rgb` and background method
:meth:`~Terminal.on_color_rgb`, as well as 676 common X11 color attribute names are now
possible, such as ``term.aquamarine_on_wheat``, :ghissue:`60`.
* introduced: ``term.move_xy``, recommended over built-in ``move`` capability, as the
argument order, ``(x, y)`` matches the return value of :meth:`~.Terminal.get_location`, and all
other common graphics library calls, :ghissue:`65`.
* introduced: :meth:`~.Terminal.move_up`, :meth:`~Terminal.move_down`, :meth:`Terminal.move_left`,
:meth:`~Terminal.move_right` which are strings that move the cursor one cell in the respective
direction, are now **also** callables for moving *n* cells to the given direction, such as
``term.move_right(9)``.
* introduced: :attr:`~Terminal.pixel_width` and :attr:`~Terminal.pixel_height` for libsixel
support or general curiosity.
* introduced: :meth:`~.Terminal.formatter` which returns callable formatters for valid text
formatters such as 'red' or 'bold_on_red', returning a
:class:`~blessed.formatters.NullCallableString` if passed an invalid text formatter.
* bugfix: prevent ``ValueError: I/O operation on closed file`` on ``sys.stdin`` in multiprocessing
environments, where the keyboard wouldn't work, anyway.
* bugfix: prevent error condition, ``ValueError: underlying buffer has been detached`` in rare
conditions where sys.__stdout__ has been detached in test frameworks. :ghissue:`126`.
* bugfix: off-by-one error in :meth:`~.Terminal.get_location`, now accounts for ``%i`` in
cursor_report, :ghissue:`94`.
* bugfix :meth:`~Terminal.split_seqs` and related functions failed to match when the color index
was greater than 15, :ghissue:`101`.
* bugfix: Context Managers, :meth:`~.Terminal.fullscreen`, :meth:`~.Terminal.hidden_cursor`, and
:meth:`~Terminal.keypad` now flush the stream after writing their sequences.
* bugfix: ``chr(127)``, ``\x7f`` has changed from keycode ``term.DELETE`` to the more common
match, ``term.BACKSPACE``, :ghissue:`115` by :ghuser:`jwezel`.
* bugfix: ensure :class:`~.FormattingOtherString` may be pickled.
* bugfix: Use ``UTF-8`` for keyboard if input encoding cannot be determined.
* deprecated: the curses ``move()`` capability is no longer recommended, suggest to use
:meth:`~.Terminal.move_xy()`, which matches the return value of :meth:`~.Terminal.get_location`.
* deprecated: ``superscript``, ``subscript``, ``shadow``, and ``dim`` are no longer "compoundable"
with colors, such as in phrase ``Terminal.blue_subscript('a')``. These attributes are not
typically supported, anyway. Use Unicode text or 256 or 24-bit color codes instead.
* deprecated: additional key names, such as ``KEY_TAB``, are no longer "injected" into the curses
module namespace.
* bugfix: briefly tried calling :func:`curses.setupterm` with :attr:`os.devnull` as the file
descriptor, reverted. :ghissue:`59`.
* deprecated: :meth:`~Terminal.inkey` no longer raises RuntimeError when :attr:`~Terminal.stream`
is not a terminal, programs using :meth:`~Terminal.inkey` to block indefinitely if a keyboard is
not attached. :ghissue:`69`.
* deprecated: using argument ``_intr_continue`` to method :meth:`~Terminal.kbhit`, behavior is as
though such value is always True since 1.9.
* bugfix: Now imports on 3.10+
* bugfix: Fix detection of shift+arrow keys when using tmux. :ghissue:`178`.
* enhancement: Instantiate SequenceTextWrapper only once in
:meth:`~.Terminal.wrap`. :ghissue:`184`.
1.16
* introduced: Windows support?! :ghpull:`110` by :ghuser:`avylove`.
1.15
* enhancement: disable timing integration tests for keyboard routines.
* enhancement: Support python 3.7. :ghpull:`102`.
* enhancement: Various fixes to test automation :ghpull:`108`
1.14
* bugfix: :meth:`~.Terminal.wrap` misbehaved for text containing newlines,
:ghissue:`74`.
* bugfix: TypeError when using ``PYTHONOPTIMIZE=2`` environment variable,
:ghissue:`84`.
* bugfix: define ``blessed.__version__`` value,
:ghissue:`92`.
* bugfix: detect sequences ``\x1b[0K`` and ``\x1b2K``,
:ghissue:`95`.
1.13
* enhancement: :meth:`~.Terminal.split_seqs` introduced, and 4x cost
reduction in related sequence-aware functions, :ghissue:`29`.
* deprecated: ``blessed.sequences.measure_length`` function superseded by
:func:`~.iter_parse` if necessary.
* deprecated: warnings about "binary-packed capabilities" are no longer
emitted on strange terminal types, making best effort.
1.12
* enhancement: :meth:`~.Terminal.get_location` returns the ``(row, col)``
position of the cursor at the time of call for attached terminal.
* enhancement: a keyboard now detected as *stdin* when
:paramref:`~.Terminal.__init__.stream` is :obj:`sys.stderr`.
1.11
* enhancement: :meth:`~.Terminal.inkey` can return more quickly for
combinations such as ``Alt + Z`` when ``MetaSendsEscape`` is enabled,
:ghissue:`30`.
* enhancement: :class:`~.FormattingString` may now be nested, such as
``t.red('red', t.underline('rum'))``, :ghissue:`61`
1.10
* workaround: provide ``sc`` and ``rc`` for Terminals of ``kind='ansi'``,
repairing :meth:`~.Terminal.location` :ghissue:`44`.
* bugfix: length of simple SGR reset sequence ``\x1b[m`` was not correctly
determined on all terminal types, :ghissue:`45`.
* deprecated: ``_intr_continue`` arguments introduced in 1.8 are now marked
deprecated in 1.10: beginning with python 3.5, the default behavior is as
though this argument is always True, `PEP-475
<https://www.python.org/dev/peps/pep-0475/>`_, blessed does the same.
1.9
* enhancement: :paramref:`~.Terminal.wrap.break_long_words` now supported by
:meth:`Terminal.wrap`
* Ignore :class:`curses.error` message ``'tparm() returned NULL'``:
this occurs on win32 or other platforms using a limited curses
implementation, such as PDCurses_, where :func:`curses.tparm` is
not implemented, or no terminal capability database is available.
* Context manager :meth:`~.keypad` emits sequences that enable
"application keys" such as the diagonal keys on the numpad.
This is equivalent to :meth:`curses.window.keypad`.
* bugfix: translate keypad application keys correctly.
* enhancement: no longer depend on the '2to3' tool for python 3 support.
* enhancement: allow ``civis`` and ``cnorm`` (*hide_cursor*, *normal_hide*)
to work with terminal-type *ansi* by emulating support by proxy.
* enhancement: new public attribute: :attr:`~.kind`: the very same as given
:paramref:`Terminal.__init__.kind` keyword argument. Or, when not given,
determined by and equivalent to the ``TERM`` Environment variable.
1.8
* enhancement: export keyboard-read function as public method ``getch()``,
so that it may be overridden by custom terminal implementers.
* enhancement: allow :meth:`~.inkey` and :meth:`~.kbhit` to return early
when interrupted by signal by passing argument ``_intr_continue=False``.
* enhancement: allow ``hpa`` and ``vpa`` (*move_x*, *move_y*) to work on
tmux(1) or screen(1) by emulating support by proxy.
* enhancement: add :meth:`~.Terminal.rstrip` and :meth:`~.Terminal.lstrip`,
strips both sequences and trailing or leading whitespace, respectively.
* enhancement: include wcwidth_ library support for
:meth:`~.Terminal.length`: the printable width of many kinds of CJK
(Chinese, Japanese, Korean) ideographs and various combining characters
may now be determined.
* enhancement: better support for detecting the length or sequences of
externally-generated *ecma-48* codes when using ``xterm`` or ``aixterm``.
* bugfix: when :func:`locale.getpreferredencoding` returns empty string or
an encoding that is not valid for ``codecs.getincrementaldecoder``,
fallback to ASCII and emit a warning.
* bugfix: ensure :class:`~.FormattingString` and
:class:`~.ParameterizingString` may be pickled.
* bugfix: allow `~.inkey` and related to be called without a keyboard.
* **change**: ``term.keyboard_fd`` is set ``None`` if ``stream`` or
``sys.stdout`` is not a tty, making ``term.inkey()``, ``term.cbreak()``,
``term.raw()``, no-op.
* bugfix: ``\x1bOH`` (KEY_HOME) was incorrectly mapped as KEY_LEFT.
1.7
* Forked github project `erikrose/blessings`_ to `jquast/blessed`_, this
project was previously known as **blessings** version 1.6 and prior.
* introduced: context manager :meth:`~.cbreak`, which is equivalent to
entering terminal state by :func:`tty.setcbreak` and returning
on exit, as well as the lesser recommended :meth:`~.raw`,
pairing from :func:`tty.setraw`.
* introduced: :meth:`~.inkey`, which will return one or more characters
received by the keyboard as a unicode sequence, with additional attributes
:attr:`~.Keystroke.code` and :attr:`~.Keystroke.name`. This allows
application keys (such as the up arrow, or home key) to be detected.
Optional value :paramref:`~.inkey.timeout` allows for timed poll.
* introduced: :meth:`~.Terminal.center`, :meth:`~.Terminal.rjust`,
:meth:`~.Terminal.ljust`, allowing text containing sequences to be aligned
to detected horizontal screen width, or by
:paramref:`~.Terminal.center.width` specified.
* introduced: :meth:`~.wrap` method. Allows text containing sequences to be
word-wrapped without breaking mid-sequence, honoring their printable width.
* introduced: :meth:`~.Terminal.strip`, strips all sequences *and*
whitespace.
* introduced: :meth:`~.Terminal.strip_seqs` strip only sequences.
* introduced: :meth:`~.Terminal.rstrip` and :meth:`~.Terminal.lstrip` strips
both sequences and trailing or leading whitespace, respectively.
* bugfix: cannot call :func:`curses.setupterm` more than once per process
(from :meth:`Terminal.__init__`): Previously, blessed pretended
to support several instances of different Terminal :attr:`~.kind`, but was
actually using the :attr:`~.kind` specified by the first instantiation of
:class:`~.Terminal`. A warning is now issued. Although this is
misbehavior is still allowed, a :class:`warnings.WarningMessage` is now
emitted to notify about subsequent terminal misbehavior.
* bugfix: resolved issue where :attr:`~.number_of_colors` fails when
:attr:`~.does_styling` is ``False``. Resolves issue where piping tests
output would fail.
* bugfix: warn and set :attr:`~.does_styling` to ``False`` when the given
:attr:`~.kind` is not found in the terminal capability database.
* bugfix: allow unsupported terminal capabilities to be callable just as
supported capabilities, so that the return value of
:attr:`~.color`\(n) may be called on terminals without color
capabilities.
* bugfix: for terminals without underline, such as vt220,
``term.underline('text')`` would emit ``'text' + term.normal``.
Now it emits only ``'text'``.
* enhancement: some attributes are now properties, raise exceptions when
assigned.
* enhancement: pypy is now a supported python platform implementation.
* enhancement: removed pokemon ``curses.error`` exceptions.
* enhancement: do not ignore :class:`curses.error` exceptions, unhandled
curses errors are legitimate errors and should be reported as a bug.
* enhancement: converted nose tests to pytest, merged travis and tox.
* enhancement: pytest fixtures, paired with a new ``@as_subprocess``
decorator
are used to test a multitude of terminal types.
* enhancement: test accessories ``@as_subprocess`` resolves various issues
with different terminal types that previously went untested.
* deprecation: python2.5 is no longer supported (as tox does not supported).
1.6
* Add :attr:`~.does_styling`. This takes :attr:`~.force_styling`
into account and should replace most uses of :attr:`~.is_a_tty`.
* Make :attr:`~.is_a_tty` a read-only property like :attr:`~.does_styling`.
Writing to it never would have done anything constructive.
* Add :meth:`~.fullscreen`` and :meth:`hidden_cursor` to the
auto-generated docs.
1.5.1
* Clean up fabfile, removing the redundant ``test`` command.
* Add Travis support.
* Make ``python setup.py test`` work without spurious errors on 2.6.
* Work around a tox parsing bug in its config file.
* Make context managers clean up after themselves even if there's an
exception (`Vitja Makarov #29 <https://github.com/erikrose/blessings/pull/29>`).
* Parameterizing a capability no longer crashes when there is no tty
(`<Vitja Makarov #31 <https://github.com/erikrose/blessings/pull/31>`)
1.5
* Add syntactic sugar and documentation for ``enter_fullscreen``
and ``exit_fullscreen``.
* Add context managers :meth:`~.fullscreen` and :meth:`~.hidden_cursor`.
* Now you can force a :class:`~.Terminal` to never to emit styles by
passing keyword argument ``force_styling=None``.
1.4
* Add syntactic sugar for cursor visibility control and single-space-movement
capabilities.
* Endorse the :meth:`~.location` context manager for restoring cursor
position after a series of manual movements.
* Fix a bug in which :meth:`~.location` that wouldn't do anything when
passed zeros.
* Allow tests to be run with ``python setup.py test``.
1.3
* Added :attr:`~.number_of_colors`, which tells you how many colors the
terminal supports.
* Made :attr:`~.color`\(n) and :attr:`~.on_color`\(n) callable to wrap a
string, like the named colors can. Also, make them both fall back to the
``setf`` and ``setb`` capabilities (like the named colors do) if the
termcap entries for ``setaf`` and ``setab`` are not available.
* Allowed :attr:`~.color` to act as an unparametrized string, not just a
callable.
* Made :attr:`~.height` and :attr:`~.width` examine any passed-in stream
before falling back to stdout (This rarely if ever affects actual behavior;
it's mostly philosophical).
* Made caching simpler and slightly more efficient.
* Got rid of a reference cycle between :class:`~.Terminal` and
:class:`~.FormattingString`.
* Updated docs to reflect that terminal addressing (as in :meth:`~location`)
is 0-based.
1.2
* Added support for Python 3! We need 3.2.3 or greater, because the curses
library couldn't decide whether to accept strs or bytes before that
(https://bugs.python.org/issue10570).
* Everything that comes out of the library is now unicode. This lets us
support Python 3 without making a mess of the code, and Python 2 should
continue to work unless you were testing types (and badly). Please file a
bug if this causes trouble for you.
* Changed to the MIT License for better world domination.
* Added Sphinx docs.
1.1
* Added nicely named attributes for colors.
* Introduced compound formatting.
* Added wrapper behavior for styling and colors.
* Let you force capabilities to be non-empty, even if the output stream is
not a terminal.
* Added :attr:`~.is_a_tty` to determine whether the output stream is a
terminal.
* Sugared the remaining interesting string capabilities.
* Allow :meth:`~.location` to operate on just an x *or* y coordinate.
1.0
* Extracted Blessed from `nose-progressive`_.
.. _`nose-progressive`: https://pypi.org/project/nose-progressive/
.. _`erikrose/blessings`: https://github.com/erikrose/blessings
.. _`jquast/blessed`: https://github.com/jquast/blessed
.. _`issue tracker`: https://github.com/jquast/blessed/issues/
.. _curses: https://docs.python.org/library/curses.html
.. _colorama: https://pypi.python.org/pypi/colorama
.. _wcwidth: https://pypi.org/project/wcwidth/
.. _`cbreak(3)`: http://www.openbsd.org/cgi-bin/man.cgi?query=cbreak&apropos=0&sektion=3
.. _`curs_getch(3)`: http://www.openbsd.org/cgi-bin/man.cgi?query=curs_getch&apropos=0&sektion=3
.. _`termios(4)`: http://www.openbsd.org/cgi-bin/man.cgi?query=termios&apropos=0&sektion=4
.. _`terminfo(5)`: http://www.openbsd.org/cgi-bin/man.cgi?query=terminfo&apropos=0&sektion=5
.. _tigetstr: http://www.openbsd.org/cgi-bin/man.cgi?query=tigetstr&sektion=3
.. _tparm: http://www.openbsd.org/cgi-bin/man.cgi?query=tparm&sektion=3
.. _`API Documentation`: http://blessed.rtfd.org
.. _`PDCurses`: https://www.lfd.uci.edu/~gohlke/pythonlibs/#curses
.. _`ansi`: https://github.com/tehmaze/ansi
Generated by dwww version 1.15 on Thu Aug 28 22:47:42 CEST 2025.