Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit bcf2b59

Browse files
pitroupitrou
committed
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.
1 parent 4195b5c commit bcf2b59

10 files changed

Lines changed: 339 additions & 5 deletions

File tree

‎Doc/library/os.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1411,6 +1411,43 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
14111411
.. versionadded:: 3.3
14121412

14131413

1414+
.. _terminal-size:
1415+
1416+
Querying the size of a terminal
1417+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1418+
1419+
.. versionadded:: 3.3
1420+
1421+
.. function:: get_terminal_size(fd=STDOUT_FILENO)
1422+
1423+
Return the size of the terminal window as ``(columns, lines)``,
1424+
tuple of type :class:`terminal_size`.
1425+
1426+
The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard
1427+
output) specifies which file descriptor should be queried.
1428+
1429+
If the file descriptor is not connected to a terminal, an :exc:`OSError`
1430+
is thrown.
1431+
1432+
:func:`shutil.get_terminal_size` is the high-level function which
1433+
should normally be used, ``os.get_terminal_size`` is the low-level
1434+
implementation.
1435+
1436+
Availability: Unix, Windows.
1437+
1438+
.. class:: terminal_size(tuple)
1439+
1440+
A tuple of ``(columns, lines)`` for holding terminal window size.
1441+
1442+
.. attribute:: columns
1443+
1444+
Width of the terminal window in characters.
1445+
1446+
.. attribute:: lines
1447+
1448+
Height of the terminal window in characters.
1449+
1450+
14141451
.. _os-file-dir:
14151452

14161453
Files and Directories

‎Doc/library/shutil.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -459,3 +459,36 @@ The resulting archive contains::
459459
-rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa
460460
-rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub
461461
-rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts
462+
463+
464+
Querying the size of the output terminal
465+
----------------------------------------
466+
467+
.. versionadded:: 3.3
468+
469+
.. function:: get_terminal_size(fallback=(columns, lines))
470+
471+
Get the size of the terminal window.
472+
473+
For each of the two dimensions, the environment variable, ``COLUMNS``
474+
and ``LINES`` respectively, is checked. If the variable is defined and
475+
the value is a positive integer, it is used.
476+
477+
When ``COLUMNS`` or ``LINES`` is not defined, which is the common case,
478+
the terminal connected to :data:`sys.__stdout__` is queried
479+
by invoking :func:`os.get_terminal_size`.
480+
481+
If the terminal size cannot be successfully queried, either because
482+
the system doesn't support querying, or because we are not
483+
connected to a terminal, the value given in ``fallback`` parameter
484+
is used. ``fallback`` defaults to ``(80, 24)`` which is the default
485+
size used by many terminal emulators.
486+
487+
The value returned is a named tuple of type :class:`os.terminal_size`.
488+
489+
See also: The Single UNIX Specification, Version 2,
490+
`Other Environment Variables`_.
491+
492+
.. _`Other Environment Variables`:
493+
http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003
494+

‎Lib/shutil.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -878,3 +878,46 @@ def chown(path, user=None, group=None):
878878
raise LookupError("no such group: {!r}".format(group))
879879

880880
os.chown(path, _user, _group)
881+
882+
def get_terminal_size(fallback=(80, 24)):
883+
"""Get the size of the terminal window.
884+
885+
For each of the two dimensions, the environment variable, COLUMNS
886+
and LINES respectively, is checked. If the variable is defined and
887+
the value is a positive integer, it is used.
888+
889+
When COLUMNS or LINES is not defined, which is the common case,
890+
the terminal connected to sys.__stdout__ is queried
891+
by invoking os.get_terminal_size.
892+
893+
If the terminal size cannot be successfully queried, either because
894+
the system doesn't support querying, or because we are not
895+
connected to a terminal, the value given in fallback parameter
896+
is used. Fallback defaults to (80, 24) which is the default
897+
size used by many terminal emulators.
898+
899+
The value returned is a named tuple of type os.terminal_size.
900+
"""
901+
# columns, lines are the working values
902+
try:
903+
columns = int(os.environ['COLUMNS'])
904+
except (KeyError, ValueError):
905+
columns = 0
906+
907+
try:
908+
lines = int(os.environ['LINES'])
909+
except (KeyError, ValueError):
910+
lines = 0
911+
912+
# only query if necessary
913+
if columns <= 0 or lines <= 0:
914+
try:
915+
size = os.get_terminal_size(sys.__stdout__.fileno())
916+
except (NameError, OSError):
917+
size = os.terminal_size(fallback)
918+
if columns <= 0:
919+
columns = size.columns
920+
if lines <= 0:
921+
lines = size.lines
922+
923+
return os.terminal_size((columns, lines))

‎Lib/test/test_os.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1840,6 +1840,43 @@ def test_symlink(self):
18401840
os.symlink, filename, filename)
18411841

18421842

1843+
@unittest.skipUnless(hasattr(os, 'get_terminal_size'), "requires os.get_terminal_size")
1844+
class TermsizeTests(unittest.TestCase):
1845+
def test_does_not_crash(self):
1846+
"""Check if get_terminal_size() returns a meaningful value.
1847+
1848+
There's no easy portable way to actually check the size of the
1849+
terminal, so let's check if it returns something sensible instead.
1850+
"""
1851+
try:
1852+
size = os.get_terminal_size()
1853+
except OSError as e:
1854+
if e.errno == errno.EINVAL or sys.platform == "win32":
1855+
# Under win32 a generic OSError can be thrown if the
1856+
# handle cannot be retrieved
1857+
self.skipTest("failed to query terminal size")
1858+
raise
1859+
1860+
self.assertGreater(size.columns, 0)
1861+
self.assertGreater(size.lines, 0)
1862+
1863+
def test_stty_match(self):
1864+
"""Check if stty returns the same results
1865+
1866+
stty actually tests stdin, so get_terminal_size is invoked on
1867+
stdin explicitly. If stty succeeded, then get_terminal_size()
1868+
should work too.
1869+
"""
1870+
try:
1871+
size = subprocess.check_output(['stty', 'size']).decode().split()
1872+
except (FileNotFoundError, subprocess.CalledProcessError):
1873+
self.skipTest("stty invocation failed")
1874+
expected = (int(size[1]), int(size[0])) # reversed order
1875+
1876+
actual = os.get_terminal_size(sys.__stdin__.fileno())
1877+
self.assertEqual(expected, actual)
1878+
1879+
18431880
@support.reap_threads
18441881
def test_main():
18451882
support.run_unittest(
@@ -1866,6 +1903,7 @@ def test_main():
18661903
ProgramPriorityTests,
18671904
ExtendedAttributeTests,
18681905
Win32DeprecatedBytesAPI,
1906+
TermsizeTests,
18691907
)
18701908

18711909
if __name__ == "__main__":

‎Lib/test/test_shutil.py‎

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
import os.path
1010
import errno
1111
import functools
12+
import subprocess
1213
from test import support
1314
from test.support import TESTFN
1415
from os.path import splitdrive
@@ -1267,10 +1268,55 @@ def test_move_dir_caseinsensitive(self):
12671268
finally:
12681269
os.rmdir(dst_dir)
12691270

1271+
class TermsizeTests(unittest.TestCase):
1272+
def test_does_not_crash(self):
1273+
"""Check if get_terminal_size() returns a meaningful value.
1274+
1275+
There's no easy portable way to actually check the size of the
1276+
terminal, so let's check if it returns something sensible instead.
1277+
"""
1278+
size = shutil.get_terminal_size()
1279+
self.assertGreater(size.columns, 0)
1280+
self.assertGreater(size.lines, 0)
1281+
1282+
def test_os_environ_first(self):
1283+
"Check if environment variables have precedence"
1284+
1285+
with support.EnvironmentVarGuard() as env:
1286+
env['COLUMNS'] = '777'
1287+
size = shutil.get_terminal_size()
1288+
self.assertEqual(size.columns, 777)
1289+
1290+
with support.EnvironmentVarGuard() as env:
1291+
env['LINES'] = '888'
1292+
size = shutil.get_terminal_size()
1293+
self.assertEqual(size.lines, 888)
1294+
1295+
@unittest.skipUnless(os.isatty(sys.__stdout__.fileno()), "not on tty")
1296+
def test_stty_match(self):
1297+
"""Check if stty returns the same results ignoring env
1298+
1299+
This test will fail if stdin and stdout are connected to
1300+
different terminals with different sizes. Nevertheless, such
1301+
situations should be pretty rare.
1302+
"""
1303+
try:
1304+
size = subprocess.check_output(['stty', 'size']).decode().split()
1305+
except (FileNotFoundError, subprocess.CalledProcessError):
1306+
self.skipTest("stty invocation failed")
1307+
expected = (int(size[1]), int(size[0])) # reversed order
1308+
1309+
with support.EnvironmentVarGuard() as env:
1310+
del env['LINES']
1311+
del env['COLUMNS']
1312+
actual = shutil.get_terminal_size()
1313+
1314+
self.assertEqual(expected, actual)
12701315

12711316

12721317
def test_main():
1273-
support.run_unittest(TestShutil, TestMove, TestCopyFile)
1318+
support.run_unittest(TestShutil, TestMove, TestCopyFile,
1319+
TermsizeTests)
12741320

12751321
if __name__ == '__main__':
12761322
test_main()

‎Misc/NEWS‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,10 @@ Core and Builtins
466466
Library
467467
-------
468468

469+
- Issue #13609: Add two functions to query the terminal size:
470+
os.get_terminal_size (low level) and shutil.get_terminal_size (high level).
471+
Patch by Zbigniew Jędrzejewski-Szmek.
472+
469473
- Issue #13845: On Windows, time.time() now uses GetSystemTimeAsFileTime()
470474
instead of ftime() to have a resolution of 100 ns instead of 1 ms (the clock
471475
accuracy is between 0.5 ms and 15 ms).

0 commit comments

Comments
 (0)