[Python-checkins] cpython: Issue #13609: Add two functions to query the terminal size:
antoine.pitrou
python-checkins at python.org
Wed Feb 8 23:31:30 CET 2012
http://hg.python.org/cpython/rev/c92f8de398ed
changeset: 74835:c92f8de398ed
user: Antoine Pitrou <solipsis at pitrou.net>
date: Wed Feb 08 23:28:36 2012 +0100
summary:
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.
files:
Doc/library/os.rst | 37 +++++++
Doc/library/shutil.rst | 33 +++++++
Lib/shutil.py | 43 +++++++++
Lib/test/test_os.py | 38 ++++++++
Lib/test/test_shutil.py | 48 ++++++++++-
Misc/NEWS | 4 +
Modules/posixmodule.c | 130 ++++++++++++++++++++++++++++
configure | 6 +-
configure.in | 2 +-
pyconfig.h.in | 3 +
10 files changed, 339 insertions(+), 5 deletions(-)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1411,6 +1411,43 @@
.. 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
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -459,3 +459,36 @@
-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
+
diff --git a/Lib/shutil.py b/Lib/shutil.py
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -878,3 +878,46 @@
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))
diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py
--- a/Lib/test/test_os.py
+++ b/Lib/test/test_os.py
@@ -1840,6 +1840,43 @@
os.symlink, filename, filename)
+ at 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 @@
ProgramPriorityTests,
ExtendedAttributeTests,
Win32DeprecatedBytesAPI,
+ TermsizeTests,
)
if __name__ == "__main__":
diff --git a/Lib/test/test_shutil.py b/Lib/test/test_shutil.py
--- a/Lib/test/test_shutil.py
+++ b/Lib/test/test_shutil.py
@@ -9,6 +9,7 @@
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 @@
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()
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -466,6 +466,10 @@
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).
diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -125,6 +125,18 @@
#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 @@
#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
@@ -10945,6 +11065,9 @@
{"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 @@
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 @@
#endif /* __APPLE__ */
+
+ PyModule_AddObject(m, "terminal_size", (PyObject*) &TerminalSizeType);
+
return m;
}
diff --git a/configure b/configure
--- a/configure
+++ b/configure
@@ -6144,7 +6144,7 @@
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 @@
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
diff --git a/configure.in b/configure.in
--- a/configure.in
+++ b/configure.in
@@ -1334,7 +1334,7 @@
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 \
diff --git a/pyconfig.h.in b/pyconfig.h.in
--- a/pyconfig.h.in
+++ b/pyconfig.h.in
@@ -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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list