mirror of
https://github.com/classilla/tenfourfox.git
synced 2024-06-11 09:29:49 +00:00
451 lines
18 KiB
Python
451 lines
18 KiB
Python
from collections import defaultdict
|
|
import curses
|
|
from curses import tigetstr, tigetnum, setupterm, tparm
|
|
from fcntl import ioctl
|
|
try:
|
|
from io import UnsupportedOperation as IOUnsupportedOperation
|
|
except ImportError:
|
|
class IOUnsupportedOperation(Exception):
|
|
"""A dummy exception to take the place of Python 3's ``io.UnsupportedOperation`` in Python 2"""
|
|
pass
|
|
import os
|
|
from os import isatty, environ
|
|
from platform import python_version_tuple
|
|
import struct
|
|
import sys
|
|
from termios import TIOCGWINSZ
|
|
|
|
|
|
if ('3', '0', '0') <= python_version_tuple() < ('3', '2', '2+'): # Good till 3.2.10
|
|
# Python 3.x < 3.2.3 has a bug in which tparm() erroneously takes a string.
|
|
raise ImportError('Blessings needs Python 3.2.3 or greater for Python 3 '
|
|
'support due to http://bugs.python.org/issue10570.')
|
|
|
|
|
|
__all__ = ['Terminal']
|
|
|
|
|
|
class Terminal(object):
|
|
"""An abstraction around terminal capabilities
|
|
|
|
Unlike curses, this doesn't require clearing the screen before doing
|
|
anything, and it's friendlier to use. It keeps the endless calls to
|
|
``tigetstr()`` and ``tparm()`` out of your code, and it acts intelligently
|
|
when somebody pipes your output to a non-terminal.
|
|
|
|
Instance attributes:
|
|
|
|
``stream``
|
|
The stream the terminal outputs to. It's convenient to pass the stream
|
|
around with the terminal; it's almost always needed when the terminal
|
|
is and saves sticking lots of extra args on client functions in
|
|
practice.
|
|
``is_a_tty``
|
|
Whether ``stream`` appears to be a terminal. You can examine this value
|
|
to decide whether to draw progress bars or other frippery.
|
|
|
|
"""
|
|
def __init__(self, kind=None, stream=None, force_styling=False):
|
|
"""Initialize the terminal.
|
|
|
|
If ``stream`` is not a tty, I will default to returning an empty
|
|
Unicode string for all capability values, so things like piping your
|
|
output to a file won't strew escape sequences all over the place. The
|
|
``ls`` command sets a precedent for this: it defaults to columnar
|
|
output when being sent to a tty and one-item-per-line when not.
|
|
|
|
:arg kind: A terminal string as taken by ``setupterm()``. Defaults to
|
|
the value of the ``TERM`` environment variable.
|
|
:arg stream: A file-like object representing the terminal. Defaults to
|
|
the original value of stdout, like ``curses.initscr()`` does.
|
|
:arg force_styling: Whether to force the emission of capabilities, even
|
|
if we don't seem to be in a terminal. This comes in handy if users
|
|
are trying to pipe your output through something like ``less -r``,
|
|
which supports terminal codes just fine but doesn't appear itself
|
|
to be a terminal. Just expose a command-line option, and set
|
|
``force_styling`` based on it. Terminal initialization sequences
|
|
will be sent to ``stream`` if it has a file descriptor and to
|
|
``sys.__stdout__`` otherwise. (``setupterm()`` demands to send them
|
|
somewhere, and stdout is probably where the output is ultimately
|
|
headed. If not, stderr is probably bound to the same terminal.)
|
|
|
|
"""
|
|
if stream is None:
|
|
stream = sys.__stdout__
|
|
try:
|
|
stream_descriptor = (stream.fileno() if hasattr(stream, 'fileno')
|
|
and callable(stream.fileno)
|
|
else None)
|
|
except IOUnsupportedOperation:
|
|
stream_descriptor = None
|
|
|
|
self.is_a_tty = stream_descriptor is not None and isatty(stream_descriptor)
|
|
self._does_styling = self.is_a_tty or force_styling
|
|
|
|
# The desciptor to direct terminal initialization sequences to.
|
|
# sys.__stdout__ seems to always have a descriptor of 1, even if output
|
|
# is redirected.
|
|
self._init_descriptor = (sys.__stdout__.fileno()
|
|
if stream_descriptor is None
|
|
else stream_descriptor)
|
|
if self._does_styling:
|
|
# Make things like tigetstr() work. Explicit args make setupterm()
|
|
# work even when -s is passed to nosetests. Lean toward sending
|
|
# init sequences to the stream if it has a file descriptor, and
|
|
# send them to stdout as a fallback, since they have to go
|
|
# somewhere.
|
|
setupterm(kind or environ.get('TERM', 'unknown'),
|
|
self._init_descriptor)
|
|
|
|
self.stream = stream
|
|
|
|
# Sugary names for commonly-used capabilities, intended to help avoid trips
|
|
# to the terminfo man page and comments in your code:
|
|
_sugar = dict(
|
|
# Don't use "on" or "bright" as an underscore-separated chunk in any of
|
|
# these (e.g. on_cology or rock_on) so we don't interfere with
|
|
# __getattr__.
|
|
save='sc',
|
|
restore='rc',
|
|
|
|
clear_eol='el',
|
|
clear_bol='el1',
|
|
clear_eos='ed',
|
|
position='cup', # deprecated
|
|
move='cup',
|
|
move_x='hpa',
|
|
move_y='vpa',
|
|
|
|
reset_colors='op', # oc doesn't work on my OS X terminal.
|
|
|
|
normal='sgr0',
|
|
reverse='rev',
|
|
# 'bold' is just 'bold'. Similarly...
|
|
# blink
|
|
# dim
|
|
# flash
|
|
italic='sitm',
|
|
no_italic='ritm',
|
|
shadow='sshm',
|
|
no_shadow='rshm',
|
|
standout='smso',
|
|
no_standout='rmso',
|
|
subscript='ssubm',
|
|
no_subscript='rsubm',
|
|
superscript='ssupm',
|
|
no_superscript='rsupm',
|
|
underline='smul',
|
|
no_underline='rmul')
|
|
|
|
def __getattr__(self, attr):
|
|
"""Return parametrized terminal capabilities, like bold.
|
|
|
|
For example, you can say ``term.bold`` to get the string that turns on
|
|
bold formatting and ``term.normal`` to get the string that turns it off
|
|
again. Or you can take a shortcut: ``term.bold('hi')`` bolds its
|
|
argument and sets everything to normal afterward. You can even combine
|
|
things: ``term.bold_underline_red_on_bright_green('yowzers!')``.
|
|
|
|
For a parametrized capability like ``cup``, pass the parameters too:
|
|
``some_term.cup(line, column)``.
|
|
|
|
``man terminfo`` for a complete list of capabilities.
|
|
|
|
Return values are always Unicode.
|
|
|
|
"""
|
|
resolution = self._resolve_formatter(attr) if self._does_styling else NullCallableString()
|
|
setattr(self, attr, resolution) # Cache capability codes.
|
|
return resolution
|
|
|
|
@property
|
|
def height(self):
|
|
"""The height of the terminal in characters
|
|
|
|
If no stream or a stream not representing a terminal was passed in at
|
|
construction, return the dimension of the controlling terminal so
|
|
piping to things that eventually display on the terminal (like ``less
|
|
-R``) work. If a stream representing a terminal was passed in, return
|
|
the dimensions of that terminal. If there somehow is no controlling
|
|
terminal, return ``None``. (Thus, you should check that ``is_a_tty`` is
|
|
true before doing any math on the result.)
|
|
|
|
"""
|
|
return self._height_and_width()[0]
|
|
|
|
@property
|
|
def width(self):
|
|
"""The width of the terminal in characters
|
|
|
|
See ``height()`` for some corner cases.
|
|
|
|
"""
|
|
return self._height_and_width()[1]
|
|
|
|
def _height_and_width(self):
|
|
"""Return a tuple of (terminal height, terminal width)."""
|
|
# tigetnum('lines') and tigetnum('cols') update only if we call
|
|
# setupterm() again.
|
|
for descriptor in self._init_descriptor, sys.__stdout__:
|
|
try:
|
|
return struct.unpack('hhhh', ioctl(descriptor, TIOCGWINSZ, '\000' * 8))[0:2]
|
|
except IOError:
|
|
pass
|
|
return None, None # Should never get here
|
|
|
|
def location(self, x=None, y=None):
|
|
"""Return a context manager for temporarily moving the cursor.
|
|
|
|
Move the cursor to a certain position on entry, let you print stuff
|
|
there, then return the cursor to its original position::
|
|
|
|
term = Terminal()
|
|
with term.location(2, 5):
|
|
print 'Hello, world!'
|
|
for x in xrange(10):
|
|
print 'I can do it %i times!' % x
|
|
|
|
Specify ``x`` to move to a certain column, ``y`` to move to a certain
|
|
row, or both.
|
|
|
|
"""
|
|
return Location(self, x, y)
|
|
|
|
@property
|
|
def color(self):
|
|
"""Return a capability that sets the foreground color.
|
|
|
|
The capability is unparametrized until called and passed a number
|
|
(0-15), at which point it returns another string which represents a
|
|
specific color change. This second string can further be called to
|
|
color a piece of text and set everything back to normal afterward.
|
|
|
|
:arg num: The number, 0-15, of the color
|
|
|
|
"""
|
|
return ParametrizingString(self._foreground_color, self.normal)
|
|
|
|
@property
|
|
def on_color(self):
|
|
"""Return a capability that sets the background color.
|
|
|
|
See ``color()``.
|
|
|
|
"""
|
|
return ParametrizingString(self._background_color, self.normal)
|
|
|
|
@property
|
|
def number_of_colors(self):
|
|
"""Return the number of colors the terminal supports.
|
|
|
|
Common values are 0, 8, 16, 88, and 256.
|
|
|
|
Though the underlying capability returns -1 when there is no color
|
|
support, we return 0. This lets you test more Pythonically::
|
|
|
|
if term.number_of_colors:
|
|
...
|
|
|
|
We also return 0 if the terminal won't tell us how many colors it
|
|
supports, which I think is rare.
|
|
|
|
"""
|
|
# This is actually the only remotely useful numeric capability. We
|
|
# don't name it after the underlying capability, because we deviate
|
|
# slightly from its behavior, and we might someday wish to give direct
|
|
# access to it.
|
|
colors = tigetnum('colors') # Returns -1 if no color support, -2 if no such cap.
|
|
#self.__dict__['colors'] = ret # Cache it. It's not changing. (Doesn't work.)
|
|
return colors if colors >= 0 else 0
|
|
|
|
def _resolve_formatter(self, attr):
|
|
"""Resolve a sugary or plain capability name, color, or compound formatting function name into a callable capability."""
|
|
if attr in COLORS:
|
|
return self._resolve_color(attr)
|
|
elif attr in COMPOUNDABLES:
|
|
# Bold, underline, or something that takes no parameters
|
|
return self._formatting_string(self._resolve_capability(attr))
|
|
else:
|
|
formatters = split_into_formatters(attr)
|
|
if all(f in COMPOUNDABLES for f in formatters):
|
|
# It's a compound formatter, like "bold_green_on_red". Future
|
|
# optimization: combine all formatting into a single escape
|
|
# sequence.
|
|
return self._formatting_string(
|
|
u''.join(self._resolve_formatter(s) for s in formatters))
|
|
else:
|
|
return ParametrizingString(self._resolve_capability(attr))
|
|
|
|
def _resolve_capability(self, atom):
|
|
"""Return a terminal code for a capname or a sugary name, or an empty Unicode.
|
|
|
|
The return value is always Unicode, because otherwise it is clumsy
|
|
(especially in Python 3) to concatenate with real (Unicode) strings.
|
|
|
|
"""
|
|
code = tigetstr(self._sugar.get(atom, atom))
|
|
if code:
|
|
# We can encode escape sequences as UTF-8 because they never
|
|
# contain chars > 127, and UTF-8 never changes anything within that
|
|
# range..
|
|
return code.decode('utf-8')
|
|
return u''
|
|
|
|
def _resolve_color(self, color):
|
|
"""Resolve a color like red or on_bright_green into a callable capability."""
|
|
# TODO: Does curses automatically exchange red and blue and cyan and
|
|
# yellow when a terminal supports setf/setb rather than setaf/setab?
|
|
# I'll be blasted if I can find any documentation. The following
|
|
# assumes it does.
|
|
color_cap = (self._background_color if 'on_' in color else
|
|
self._foreground_color)
|
|
# curses constants go up to only 7, so add an offset to get at the
|
|
# bright colors at 8-15:
|
|
offset = 8 if 'bright_' in color else 0
|
|
base_color = color.rsplit('_', 1)[-1]
|
|
return self._formatting_string(
|
|
color_cap(getattr(curses, 'COLOR_' + base_color.upper()) + offset))
|
|
|
|
@property
|
|
def _foreground_color(self):
|
|
return self.setaf or self.setf
|
|
|
|
@property
|
|
def _background_color(self):
|
|
return self.setab or self.setb
|
|
|
|
def _formatting_string(self, formatting):
|
|
"""Return a new ``FormattingString`` which implicitly receives my notion of "normal"."""
|
|
return FormattingString(formatting, self.normal)
|
|
|
|
|
|
def derivative_colors(colors):
|
|
"""Return the names of valid color variants, given the base colors."""
|
|
return set([('on_' + c) for c in colors] +
|
|
[('bright_' + c) for c in colors] +
|
|
[('on_bright_' + c) for c in colors])
|
|
|
|
|
|
COLORS = set(['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'])
|
|
COLORS.update(derivative_colors(COLORS))
|
|
COMPOUNDABLES = (COLORS |
|
|
set(['bold', 'underline', 'reverse', 'blink', 'dim', 'italic',
|
|
'shadow', 'standout', 'subscript', 'superscript']))
|
|
|
|
|
|
class ParametrizingString(unicode):
|
|
"""A Unicode string which can be called to parametrize it as a terminal capability"""
|
|
def __new__(cls, formatting, normal=None):
|
|
"""Instantiate.
|
|
|
|
:arg normal: If non-None, indicates that, once parametrized, this can
|
|
be used as a ``FormattingString``. The value is used as the
|
|
"normal" capability.
|
|
|
|
"""
|
|
new = unicode.__new__(cls, formatting)
|
|
new._normal = normal
|
|
return new
|
|
|
|
def __call__(self, *args):
|
|
try:
|
|
# Re-encode the cap, because tparm() takes a bytestring in Python
|
|
# 3. However, appear to be a plain Unicode string otherwise so
|
|
# concats work.
|
|
parametrized = tparm(self.encode('utf-8'), *args).decode('utf-8')
|
|
return (parametrized if self._normal is None else
|
|
FormattingString(parametrized, self._normal))
|
|
except curses.error:
|
|
# Catch "must call (at least) setupterm() first" errors, as when
|
|
# running simply `nosetests` (without progressive) on nose-
|
|
# progressive. Perhaps the terminal has gone away between calling
|
|
# tigetstr and calling tparm.
|
|
return u''
|
|
except TypeError:
|
|
# If the first non-int (i.e. incorrect) arg was a string, suggest
|
|
# something intelligent:
|
|
if len(args) == 1 and isinstance(args[0], basestring):
|
|
raise TypeError(
|
|
'A native or nonexistent capability template received '
|
|
'%r when it was expecting ints. You probably misspelled a '
|
|
'formatting call like bright_red_on_white(...).' % args)
|
|
else:
|
|
# Somebody passed a non-string; I don't feel confident
|
|
# guessing what they were trying to do.
|
|
raise
|
|
|
|
|
|
class FormattingString(unicode):
|
|
"""A Unicode string which can be called upon a piece of text to wrap it in formatting"""
|
|
def __new__(cls, formatting, normal):
|
|
new = unicode.__new__(cls, formatting)
|
|
new._normal = normal
|
|
return new
|
|
|
|
def __call__(self, text):
|
|
"""Return a new string that is ``text`` formatted with my contents.
|
|
|
|
At the beginning of the string, I prepend the formatting that is my
|
|
contents. At the end, I append the "normal" sequence to set everything
|
|
back to defaults. The return value is always a Unicode.
|
|
|
|
"""
|
|
return self + text + self._normal
|
|
|
|
|
|
class NullCallableString(unicode):
|
|
"""A dummy class to stand in for ``FormattingString`` and ``ParametrizingString``
|
|
|
|
A callable bytestring that returns an empty Unicode when called with an int
|
|
and the arg otherwise. We use this when there is no tty and so all
|
|
capabilities are blank.
|
|
|
|
"""
|
|
def __new__(cls):
|
|
new = unicode.__new__(cls, u'')
|
|
return new
|
|
|
|
def __call__(self, arg):
|
|
if isinstance(arg, int):
|
|
return u''
|
|
return arg # TODO: Force even strs in Python 2.x to be unicodes? Nah. How would I know what encoding to use to convert it?
|
|
|
|
|
|
def split_into_formatters(compound):
|
|
"""Split a possibly compound format string into segments.
|
|
|
|
>>> split_into_formatters('bold_underline_bright_blue_on_red')
|
|
['bold', 'underline', 'bright_blue', 'on_red']
|
|
|
|
"""
|
|
merged_segs = []
|
|
# These occur only as prefixes, so they can always be merged:
|
|
mergeable_prefixes = ['on', 'bright', 'on_bright']
|
|
for s in compound.split('_'):
|
|
if merged_segs and merged_segs[-1] in mergeable_prefixes:
|
|
merged_segs[-1] += '_' + s
|
|
else:
|
|
merged_segs.append(s)
|
|
return merged_segs
|
|
|
|
|
|
class Location(object):
|
|
"""Context manager for temporarily moving the cursor"""
|
|
def __init__(self, term, x=None, y=None):
|
|
self.x, self.y = x, y
|
|
self.term = term
|
|
|
|
def __enter__(self):
|
|
"""Save position and move to the requested column, row, or both."""
|
|
self.term.stream.write(self.term.save) # save position
|
|
if self.x and self.y:
|
|
self.term.stream.write(self.term.move(self.y, self.x))
|
|
elif self.x:
|
|
self.term.stream.write(self.term.move_x(self.x))
|
|
elif self.y:
|
|
self.term.stream.write(self.term.move_y(self.y))
|
|
|
|
def __exit__(self, type, value, tb):
|
|
"""Restore original cursor position."""
|
|
self.term.stream.write(self.term.restore)
|