Issue #13609: Add two functions to query the terminal size:

os.get_terminal_size (low level) and shutil.get_terminal_size (high level).
Patch by Zbigniew Jędrzejewski-Szmek.
This commit is contained in:
Antoine Pitrou 2012-02-08 23:28:36 +01:00
parent 4195b5caea
commit bcf2b59fb5
10 changed files with 339 additions and 5 deletions

View File

@ -1411,6 +1411,43 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
.. versionadded:: 3.3
.. _terminal-size:
Querying the size of a terminal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 3.3
.. function:: get_terminal_size(fd=STDOUT_FILENO)
Return the size of the terminal window as ``(columns, lines)``,
tuple of type :class:`terminal_size`.
The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard
output) specifies which file descriptor should be queried.
If the file descriptor is not connected to a terminal, an :exc:`OSError`
is thrown.
:func:`shutil.get_terminal_size` is the high-level function which
should normally be used, ``os.get_terminal_size`` is the low-level
implementation.
Availability: Unix, Windows.
.. class:: terminal_size(tuple)
A tuple of ``(columns, lines)`` for holding terminal window size.
.. attribute:: columns
Width of the terminal window in characters.
.. attribute:: lines
Height of the terminal window in characters.
.. _os-file-dir:
Files and Directories

View File

@ -459,3 +459,36 @@ The resulting archive contains::
-rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts
Querying the size of the output terminal
----------------------------------------
.. versionadded:: 3.3
.. function:: get_terminal_size(fallback=(columns, lines))
Get the size of the terminal window.
For each of the two dimensions, the environment variable, ``COLUMNS``
and ``LINES`` respectively, is checked. If the variable is defined and
the value is a positive integer, it is used.
When ``COLUMNS`` or ``LINES`` is not defined, which is the common case,
the terminal connected to :data:`sys.__stdout__` is queried
by invoking :func:`os.get_terminal_size`.
If the terminal size cannot be successfully queried, either because
the system doesn't support querying, or because we are not
connected to a terminal, the value given in ``fallback`` parameter
is used. ``fallback`` defaults to ``(80, 24)`` which is the default
size used by many terminal emulators.
The value returned is a named tuple of type :class:`os.terminal_size`.
See also: The Single UNIX Specification, Version 2,
`Other Environment Variables`_.
.. _`Other Environment Variables`:
http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003

View File

@ -878,3 +878,46 @@ def chown(path, user=None, group=None):
raise LookupError("no such group: {!r}".format(group))
os.chown(path, _user, _group)
def get_terminal_size(fallback=(80, 24)):
"""Get the size of the terminal window.
For each of the two dimensions, the environment variable, COLUMNS
and LINES respectively, is checked. If the variable is defined and
the value is a positive integer, it is used.
When COLUMNS or LINES is not defined, which is the common case,
the terminal connected to sys.__stdout__ is queried
by invoking os.get_terminal_size.
If the terminal size cannot be successfully queried, either because
the system doesn't support querying, or because we are not
connected to a terminal, the value given in fallback parameter
is used. Fallback defaults to (80, 24) which is the default
size used by many terminal emulators.
The value returned is a named tuple of type os.terminal_size.
"""
# columns, lines are the working values
try:
columns = int(os.environ['COLUMNS'])
except (KeyError, ValueError):
columns = 0
try:
lines = int(os.environ['LINES'])
except (KeyError, ValueError):
lines = 0
# only query if necessary
if columns <= 0 or lines <= 0:
try:
size = os.get_terminal_size(sys.__stdout__.fileno())
except (NameError, OSError):
size = os.terminal_size(fallback)
if columns <= 0:
columns = size.columns
if lines <= 0:
lines = size.lines
return os.terminal_size((columns, lines))

View File

@ -1840,6 +1840,43 @@ class Win32DeprecatedBytesAPI(unittest.TestCase):
os.symlink, filename, filename)
@unittest.skipUnless(hasattr(os, 'get_terminal_size'), "requires os.get_terminal_size")
class TermsizeTests(unittest.TestCase):
def test_does_not_crash(self):
"""Check if get_terminal_size() returns a meaningful value.
There's no easy portable way to actually check the size of the
terminal, so let's check if it returns something sensible instead.
"""
try:
size = os.get_terminal_size()
except OSError as e:
if e.errno == errno.EINVAL or sys.platform == "win32":
# Under win32 a generic OSError can be thrown if the
# handle cannot be retrieved
self.skipTest("failed to query terminal size")
raise
self.assertGreater(size.columns, 0)
self.assertGreater(size.lines, 0)
def test_stty_match(self):
"""Check if stty returns the same results
stty actually tests stdin, so get_terminal_size is invoked on
stdin explicitly. If stty succeeded, then get_terminal_size()
should work too.
"""
try:
size = subprocess.check_output(['stty', 'size']).decode().split()
except (FileNotFoundError, subprocess.CalledProcessError):
self.skipTest("stty invocation failed")
expected = (int(size[1]), int(size[0])) # reversed order
actual = os.get_terminal_size(sys.__stdin__.fileno())
self.assertEqual(expected, actual)
@support.reap_threads
def test_main():
support.run_unittest(
@ -1866,6 +1903,7 @@ def test_main():
ProgramPriorityTests,
ExtendedAttributeTests,
Win32DeprecatedBytesAPI,
TermsizeTests,
)
if __name__ == "__main__":

View File

@ -9,6 +9,7 @@ import os
import os.path
import errno
import functools
import subprocess
from test import support
from test.support import TESTFN
from os.path import splitdrive
@ -1267,10 +1268,55 @@ class TestCopyFile(unittest.TestCase):
finally:
os.rmdir(dst_dir)
class TermsizeTests(unittest.TestCase):
def test_does_not_crash(self):
"""Check if get_terminal_size() returns a meaningful value.
There's no easy portable way to actually check the size of the
terminal, so let's check if it returns something sensible instead.
"""
size = shutil.get_terminal_size()
self.assertGreater(size.columns, 0)
self.assertGreater(size.lines, 0)
def test_os_environ_first(self):
"Check if environment variables have precedence"
with support.EnvironmentVarGuard() as env:
env['COLUMNS'] = '777'
size = shutil.get_terminal_size()
self.assertEqual(size.columns, 777)
with support.EnvironmentVarGuard() as env:
env['LINES'] = '888'
size = shutil.get_terminal_size()
self.assertEqual(size.lines, 888)
@unittest.skipUnless(os.isatty(sys.__stdout__.fileno()), "not on tty")
def test_stty_match(self):
"""Check if stty returns the same results ignoring env
This test will fail if stdin and stdout are connected to
different terminals with different sizes. Nevertheless, such
situations should be pretty rare.
"""
try:
size = subprocess.check_output(['stty', 'size']).decode().split()
except (FileNotFoundError, subprocess.CalledProcessError):
self.skipTest("stty invocation failed")
expected = (int(size[1]), int(size[0])) # reversed order
with support.EnvironmentVarGuard() as env:
del env['LINES']
del env['COLUMNS']
actual = shutil.get_terminal_size()
self.assertEqual(expected, actual)
def test_main():
support.run_unittest(TestShutil, TestMove, TestCopyFile)
support.run_unittest(TestShutil, TestMove, TestCopyFile,
TermsizeTests)
if __name__ == '__main__':
test_main()

View File

@ -466,6 +466,10 @@ Core and Builtins
Library
-------
- Issue #13609: Add two functions to query the terminal size:
os.get_terminal_size (low level) and shutil.get_terminal_size (high level).
Patch by Zbigniew Jędrzejewski-Szmek.
- Issue #13845: On Windows, time.time() now uses GetSystemTimeAsFileTime()
instead of ftime() to have a resolution of 100 ns instead of 1 ms (the clock
accuracy is between 0.5 ms and 15 ms).

View File

@ -125,6 +125,18 @@ corresponding Unix manual entries for more information on calls.");
#include <dlfcn.h>
#endif
#if defined(MS_WINDOWS)
# define TERMSIZE_USE_CONIO
#elif defined(HAVE_SYS_IOCTL_H)
# include <sys/ioctl.h>
# if defined(HAVE_TERMIOS_H)
# include <termios.h>
# endif
# if defined(TIOCGWINSZ)
# define TERMSIZE_USE_IOCTL
# endif
#endif /* MS_WINDOWS */
/* Various compilers have only certain posix functions */
/* XXX Gosh I wish these were all moved into pyconfig.h */
#if defined(PYCC_VACPP) && defined(PYOS_OS2)
@ -10477,6 +10489,114 @@ posix_flistxattr(PyObject *self, PyObject *args)
#endif /* USE_XATTRS */
/* Terminal size querying */
static PyTypeObject TerminalSizeType;
PyDoc_STRVAR(TerminalSize_docstring,
"A tuple of (columns, lines) for holding terminal window size");
static PyStructSequence_Field TerminalSize_fields[] = {
{"columns", "width of the terminal window in characters"},
{"lines", "height of the terminal window in characters"},
{NULL, NULL}
};
static PyStructSequence_Desc TerminalSize_desc = {
"os.terminal_size",
TerminalSize_docstring,
TerminalSize_fields,
2,
};
#if defined(TERMSIZE_USE_CONIO) || defined(TERMSIZE_USE_IOCTL)
PyDoc_STRVAR(termsize__doc__,
"Return the size of the terminal window as (columns, lines).\n" \
"\n" \
"The optional argument fd (default standard output) specifies\n" \
"which file descriptor should be queried.\n" \
"\n" \
"If the file descriptor is not connected to a terminal, an OSError\n" \
"is thrown.\n" \
"\n" \
"This function will only be defined if an implementation is\n" \
"available for this system.\n" \
"\n" \
"shutil.get_terminal_size is the high-level function which should \n" \
"normally be used, os.get_terminal_size is the low-level implementation.");
static PyObject*
get_terminal_size(PyObject *self, PyObject *args)
{
int columns, lines;
PyObject *termsize;
int fd = fileno(stdout);
/* Under some conditions stdout may not be connected and
* fileno(stdout) may point to an invalid file descriptor. For example
* GUI apps don't have valid standard streams by default.
*
* If this happens, and the optional fd argument is not present,
* the ioctl below will fail returning EBADF. This is what we want.
*/
if (!PyArg_ParseTuple(args, "|i", &fd))
return NULL;
#ifdef TERMSIZE_USE_IOCTL
{
struct winsize w;
if (ioctl(fd, TIOCGWINSZ, &w))
return PyErr_SetFromErrno(PyExc_OSError);
columns = w.ws_col;
lines = w.ws_row;
}
#endif /* TERMSIZE_USE_IOCTL */
#ifdef TERMSIZE_USE_CONIO
{
DWORD nhandle;
HANDLE handle;
CONSOLE_SCREEN_BUFFER_INFO csbi;
switch (fd) {
case 0: nhandle = STD_INPUT_HANDLE;
break;
case 1: nhandle = STD_OUTPUT_HANDLE;
break;
case 2: nhandle = STD_ERROR_HANDLE;
break;
default:
return PyErr_Format(PyExc_ValueError, "bad file descriptor");
}
handle = GetStdHandle(nhandle);
if (handle == NULL)
return PyErr_Format(PyExc_OSError, "handle cannot be retrieved");
if (handle == INVALID_HANDLE_VALUE)
return PyErr_SetFromWindowsErr(0);
if (!GetConsoleScreenBufferInfo(handle, &csbi))
return PyErr_SetFromWindowsErr(0);
columns = csbi.srWindow.Right - csbi.srWindow.Left + 1;
lines = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
}
#endif /* TERMSIZE_USE_CONIO */
termsize = PyStructSequence_New(&TerminalSizeType);
if (termsize == NULL)
return NULL;
PyStructSequence_SET_ITEM(termsize, 0, PyLong_FromLong(columns));
PyStructSequence_SET_ITEM(termsize, 1, PyLong_FromLong(lines));
if (PyErr_Occurred()) {
Py_DECREF(termsize);
return NULL;
}
return termsize;
}
#endif /* defined(TERMSIZE_USE_CONIO) || defined(TERMSIZE_USE_IOCTL) */
static PyMethodDef posix_methods[] = {
{"access", posix_access, METH_VARARGS, posix_access__doc__},
#ifdef HAVE_TTYNAME
@ -10944,6 +11064,9 @@ static PyMethodDef posix_methods[] = {
{"listxattr", posix_listxattr, METH_VARARGS, posix_listxattr__doc__},
{"llistxattr", posix_llistxattr, METH_VARARGS, posix_llistxattr__doc__},
{"flistxattr", posix_flistxattr, METH_VARARGS, posix_flistxattr__doc__},
#endif
#if defined(TERMSIZE_USE_CONIO) || defined(TERMSIZE_USE_IOCTL)
{"get_terminal_size", get_terminal_size, METH_VARARGS, termsize__doc__},
#endif
{NULL, NULL} /* Sentinel */
};
@ -11539,6 +11662,10 @@ INITFUNC(void)
PyStructSequence_InitType(&SchedParamType, &sched_param_desc);
SchedParamType.tp_new = sched_param_new;
#endif
/* initialize TerminalSize_info */
PyStructSequence_InitType(&TerminalSizeType, &TerminalSize_desc);
Py_INCREF(&TerminalSizeType);
}
#if defined(HAVE_WAITID) && !defined(__APPLE__)
Py_INCREF((PyObject*) &WaitidResultType);
@ -11593,6 +11720,9 @@ INITFUNC(void)
#endif /* __APPLE__ */
PyModule_AddObject(m, "terminal_size", (PyObject*) &TerminalSizeType);
return m;
}

6
configure vendored
View File

@ -6144,7 +6144,7 @@ ieeefp.h io.h langinfo.h libintl.h ncurses.h process.h pthread.h \
sched.h shadow.h signal.h stdint.h stropts.h termios.h \
unistd.h utime.h \
poll.h sys/devpoll.h sys/epoll.h sys/poll.h \
sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.h \
sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.h sys/ioctl.h \
sys/kern_control.h sys/loadavg.h sys/lock.h sys/mkdev.h sys/modem.h \
sys/param.h sys/select.h sys/sendfile.h sys/socket.h sys/statvfs.h \
sys/stat.h sys/syscall.h sys/sys_domain.h sys/termio.h sys/time.h \
@ -14599,8 +14599,8 @@ esac
cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
# Files that config.status was made for.
config_files="$ac_config_files"
config_headers="$ac_config_headers"
config_files="`echo $ac_config_files`"
config_headers="`echo $ac_config_headers`"
_ACEOF

View File

@ -1334,7 +1334,7 @@ ieeefp.h io.h langinfo.h libintl.h ncurses.h process.h pthread.h \
sched.h shadow.h signal.h stdint.h stropts.h termios.h \
unistd.h utime.h \
poll.h sys/devpoll.h sys/epoll.h sys/poll.h \
sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.h \
sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.h sys/ioctl.h \
sys/kern_control.h sys/loadavg.h sys/lock.h sys/mkdev.h sys/modem.h \
sys/param.h sys/select.h sys/sendfile.h sys/socket.h sys/statvfs.h \
sys/stat.h sys/syscall.h sys/sys_domain.h sys/termio.h sys/time.h \

View File

@ -908,6 +908,9 @@
/* Define to 1 if you have the <sys/file.h> header file. */
#undef HAVE_SYS_FILE_H
/* Define to 1 if you have the <sys/ioctl.h> header file. */
#undef HAVE_SYS_IOCTL_H
/* Define to 1 if you have the <sys/kern_control.h> header file. */
#undef HAVE_SYS_KERN_CONTROL_H