Terminfo Database¶
Note
This content is not relevant to Windows.
If your application interacts with terminals (e.g. command line tools), your
application may require the availability of a terminfo
database so your
application can properly interact with the terminal. The absence of a terminal
database can result in the inability to properly colorize text, the backspace
and arrow keys not working as expected, weird behavior on window resizing, etc.
A terminfo
database is also required to use curses
or readline
module functionality without issue.
UNIX like systems almost always provide a terminfo
database which says
which features and properties various terminals have. Essentially, the
TERM
environment variable defines the current terminal [emulator] in
use and the terminfo
database converts that value to various settings.
From Python, the ncurses
library is responsible for consulting the
terminfo
database and determining how to interact with the terminal.
This interaction with the ncurses
library is typically performed from
the _curses
, _curses_panel
, and _readline
C extensions. These
C extensions are wrapped by the user-facing curses
and readline
Python modules. And these Python modules can be used from various
functionality in the Python standard library. For example, the readline
module is used to power pdb
.
PyOxidizer applications do not ship a terminfo database. Instead,
applications rely on the terminfo
database on the executing machine.
(Of course, individual applications could ship a terminfo
database if
they want: the functionality just isn’t included in PyOxidizer by default.)
The reason PyOxidizer doesn’t ship a terminfo
database is that terminal
configurations are very system and user specific: PyOxidizer wants to
respect the configuration of the environment in which applications run. The
best way to do this is to use the terminfo
database on the executing
machine instead of providing a static database that may not be properly
configured for the run-time environment.
PyOxidizer applications have the choice of various modes for resolving
the terminfo
database location. This is facilitated mainly via the
PythonInterpreterConfig.terminfo_resolution
config setting.
By default, when Python is initialized PyOxidizer will try to identify
the current operating system and choose an appropriate set of well-known
paths for that operating system. If the operating system is well-known
(such as a Debian-based Linux distribution), this set of paths is fixed.
If the operating system is not well-known, PyOxidizer will look for
terminfo
databases at common paths and use whatever paths are
present.
If all goes according to plan, the default behavior just works. On
common operating systems, the cost to the default behavior is reading
a single file from the filesystem (in order to resolve the operating
system). The overhead should be negligible. For unknown operating
systems, PyOxidizer may need to stat()
~10 paths looking for the
terminfo
database. This should also complete fairly quickly. If
the overhead is a concern for you, it is recommended to build applications
with a fixed path to the terminfo
database.
Under the hood, when PyOxidizer resolves the terminfo
database
location, it communicates these paths to ncurses
by setting the
TERMINFO_DIRS
environment variable. If the TERMINFO_DIRS
environment variable is already set at application run-time, PyOxidizer
will never overwrite it.
The ncurses
library that PyOxidizer applications ship with is also
configured to look for a terminfo
database in the current user’s
home directory (HOME
environment variable) by default, specifically
$HOME/.terminfo
). Support for termcap
databases is not enabled.
Note
terminfo
database behavior is intrinsically complicated because
various operating systems do things differently. If you notice oddities
in the interaction of PyOxidizer applications with terminals, there’s
a good chance you found a deficiency in PyOxidizer’s terminal detection
logic (which is located in the pyembed::osutils
Rust module).
Please report terminal interaction issues at https://github.com/indygreg/PyOxidizer/issues.