diff options
| -rw-r--r-- | Doc/library/os.rst | 37 | ||||
| -rw-r--r-- | Doc/library/shutil.rst | 33 | ||||
| -rw-r--r-- | Lib/shutil.py | 43 | ||||
| -rw-r--r-- | Lib/test/test_os.py | 38 | ||||
| -rw-r--r-- | Lib/test/test_shutil.py | 48 | ||||
| -rw-r--r-- | Misc/NEWS | 4 | ||||
| -rw-r--r-- | Modules/posixmodule.c | 130 | ||||
| -rwxr-xr-x | configure | 6 | ||||
| -rw-r--r-- | configure.in | 2 | ||||
| -rw-r--r-- | pyconfig.h.in | 3 |
10 files changed, 339 insertions, 5 deletions
diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 06f1452..c3dfb3d 100644 --- a/Doc/library/os.rst +++ b/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 diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 77ce6b0..bae7db8 100644 --- a/Doc/library/shutil.rst +++ b/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 + diff --git a/Lib/shutil.py b/Lib/shutil.py index db80faf..6664599 100644 --- a/Lib/shutil.py +++ b/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)) diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py index 4d27c2b..8dd745a 100644 --- a/Lib/test/test_os.py +++ b/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__": diff --git a/Lib/test/test_shutil.py b/Lib/test/test_shutil.py index c72bac2..4d0ef29 100644 --- a/Lib/test/test_shutil.py +++ b/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() @@ -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). diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index 8b2b211..0553c76 100644 --- a/Modules/posixmodule.c +++ b/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 @@ -10945,6 +11065,9 @@ static PyMethodDef posix_methods[] = { {"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; } @@ -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 diff --git a/configure.in b/configure.in index ed7f0ad..47ba787 100644 --- a/configure.in +++ b/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 \ diff --git a/pyconfig.h.in b/pyconfig.h.in index 5dd9878..efab4fd 100644 --- 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 |