diff --git a/Doc/library/os.rst b/Doc/library/os.rst --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1408,6 +1408,59 @@ .. versionadded:: 3.3 +.. _terminal-size: + +Querying the size of the output terminal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.3 + +.. function:: get_terminal_size(fallback=(columns, rows)) + + Get the size of the terminal window. + + For each of the two dimensions, the environment variable, ``COLUMNS`` + and ``ROWS`` respectively, is checked. If the variable is defined and + the value is a positive integer, it is used. + + When ``COLUMNS`` or ``ROWS`` is not defined, which is the common case, + the terminal connected to :data:`sys.__stdout__` is queried. + + 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. + + The value returned is a named tuple of type :class:`terminal_size`. + +.. function:: query_terminal_size_raw(fd=STDOUT_FILENO) + + Return the size of the terminal window as ``(columns, rows)``, + 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. If the function is not available for this system, a + :exc:`NotImplementedError` is thrown. + + :func:`get_terminal_size` is the high-level function which should normally + be used, ``query_terminal_size_raw`` is the low-level implementation. + +.. class:: terminal_size(tuple) + + A tuple of ``(columns, rows)`` for holding terminal window size. + + .. attribute:: columns + + Width of the terminal window in characters. + + .. attribute:: rows + + Height of the terminal window in characters. + + .. _os-file-dir: Files and Directories diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -469,6 +469,11 @@ (Patch submitted by Giampaolo Rodolà in :issue:`10784`.) +* XXX The :mod:`os` module has a new function :func:`~os.get_terminal_size` + to check the size of output terminal window. + + (Patch submitted by Zbigniew Jędrzejewski-Szmek in :issue:`13609`.) + * "at" functions (:issue:`4761`): * :func:`~os.faccessat` diff --git a/Lib/os.py b/Lib/os.py --- a/Lib/os.py +++ b/Lib/os.py @@ -829,3 +829,46 @@ raise TypeError("invalid fd type (%s, expected integer)" % type(fd)) import io return io.open(fd, *args, **kwargs) + +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 ROWS respectively, is checked. If the variable is defined and + the value is a positive integer, it is used. + + When COLUMNS or ROWS is not defined, which is the common case, + the terminal connected to sys.__stdout__ is queried. + + 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. + + The value returned is a named tuple of type terminal_size. + + Right now the values are not cached, but this might change. + """ + # ccc, rrr are the working values + try: + ccc = int(environ['COLUMNS']) + except (KeyError, ValueError): + ccc = 0 + + try: + rrr = int(environ['ROWS']) + except (KeyError, ValueError): + rrr = 0 + + # only query if necessary + if ccc <= 0 or rrr <= 0: + try: + size = query_terminal_size_raw(sys.__stdout__.fileno()) + except (NameError, OSError): + size = terminal_size(fallback) + if ccc <= 0: + ccc = size.columns + if rrr <= 0: + rrr = size.rows + + return terminal_size((ccc, rrr)) diff --git a/Lib/test/test_termsize.py b/Lib/test/test_termsize.py new file mode 100644 --- /dev/null +++ b/Lib/test/test_termsize.py @@ -0,0 +1,31 @@ +import unittest +import os +from test import support + +class TermsizeTests(unittest.TestCase): + def test_does_not_crash(self): + # 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 = os.get_terminal_size() + self.assertGreater(size.columns, 0) + self.assertGreater(size.rows, 0) + + def test_os_environ_first(self): + "Check if environment variables have precedence" + + with support.EnvironmentVarGuard() as env: + env['COLUMNS'] = '777' + size = os.get_terminal_size() + self.assertEqual(size.columns, 777) + + with support.EnvironmentVarGuard() as env: + env['ROWS'] = '888' + size = os.get_terminal_size() + self.assertEqual(size.rows, 888) + +def test_main(): + support.run_unittest(TermsizeTests) + +if __name__== '__main__': + test_main() diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -7289,6 +7289,9 @@ - Windows locale mapping updated to Vista. +- Issue #13609: os.get_terminal_size() and os.query_terminal_size_raw() functions + are added to check the size of the terminal window. + Tools/Demos ----------- diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -125,6 +125,18 @@ #include #endif +#if defined(MS_WINDOWS) +# define TERMSIZE_USE_CONIO +#elif defined(HAVE_SYS_IOCTL_H) +# include +# if defined(HAVE_TERMIOS_H) +# include +# 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) @@ -10496,6 +10508,102 @@ #endif /* USE_XATTRS */ + +/* Terminal size querying */ + +static PyTypeObject TerminalSizeType; + +PyDoc_STRVAR(TerminalSize_docstring, + "A tuple of (columns, rows) for holding terminal window size"); + +static PyStructSequence_Field TerminalSize_fields[] = { + {"columns", "width of the terminal window in characters"}, + {"rows", "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, rows).\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. If the function is not available for this system, a\n" \ + "NotImplementedError is thrown.\n" \ + "\n" \ + "get_terminal_size is the high-level function which should normally\n" \ + "be used, query_terminal_size_raw is the low-level implementation."); + +static PyObject* +query_terminal_size_raw(PyObject *self, PyObject *args) +{ + int columns, rows; + PyObject *termsize; + int fd = 1; /* stdout */ + + 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; + rows = 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 == INVALID_HANDLE_VALUE) + return PyErr_Format(PyExc_OSError, "invalid handle value"); + + if (!GetConsoleScreenBufferInfo(handle, &csbi)) + return PyErr_SetFromWindowsErr(GetLastError()); + + columns = csbi.srWindow.Right - csbi.srWindow.Left + 1; + rows = 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(rows)); + 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 @@ -10963,6 +11071,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) + {"query_terminal_size_raw", query_terminal_size_raw, METH_VARARGS, termsize__doc__}, +#endif {NULL, NULL} /* Sentinel */ }; @@ -11557,6 +11668,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); @@ -11611,6 +11726,9 @@ #endif /* __APPLE__ */ + + PyModule_AddObject(m, "terminal_size", (PyObject*) &TerminalSizeType); + return m; } diff --git a/configure b/configure --- a/configure +++ b/configure @@ -6147,7 +6147,7 @@ sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.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/termio.h sys/time.h \ +sys/stat.h sys/termio.h sys/time.h sys/ioctl.h \ sys/times.h sys/types.h sys/uio.h sys/un.h sys/utsname.h sys/wait.h pty.h \ libutil.h sys/resource.h netpacket/packet.h sysexits.h bluetooth.h \ bluetooth/bluetooth.h linux/tipc.h spawn.h util.h diff --git a/configure.in b/configure.in --- a/configure.in +++ b/configure.in @@ -1337,7 +1337,7 @@ sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.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/termio.h sys/time.h \ +sys/stat.h sys/termio.h sys/time.h sys/ioctl.h \ sys/times.h sys/types.h sys/uio.h sys/un.h sys/utsname.h sys/wait.h pty.h \ libutil.h sys/resource.h netpacket/packet.h sysexits.h bluetooth.h \ bluetooth/bluetooth.h linux/tipc.h spawn.h util.h) diff --git a/pyconfig.h.in b/pyconfig.h.in --- a/pyconfig.h.in +++ b/pyconfig.h.in @@ -905,6 +905,9 @@ /* Define to 1 if you have the header file. */ #undef HAVE_SYS_FILE_H +/* Define to 1 if you have the header file. */ +#undef HAVE_SYS_IOCTL_H + /* Define to 1 if you have the header file. */ #undef HAVE_SYS_LOADAVG_H