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.

Doc/library/os.rst

@@ -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

Doc/library/shutil.rst

@@ -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
+

Lib/shutil.py

@@ -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))

Lib/test/test_os.py

@@ -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__":

Lib/test/test_shutil.py

@@ -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()

Misc/NEWS

@@ -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).

Modules/posixmodule.c

@@ -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;
 
 }

configure

@@ -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_files="`echo $ac_config_files`"
-config_headers="$ac_config_headers"
+config_headers="`echo $ac_config_headers`"
 
 _ACEOF
 

configure.in

@@ -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 \

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