Set default keyword argument timeout of 1 for get_dec_mode, get_location, get_fgcolor, get_bgcolor. (#315)

Author: jquast

bin/color_query.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+"""Query terminal foreground and background colors."""
+from blessed import Terminal
+
+term = Terminal()
+
+# Get foreground color
+r, g, b = term.get_fgcolor()
+if (r, g, b) != (-1, -1, -1):
+ print(f"Foreground color: RGB({r}, {g}, {b})")
+ print(f" Hex: #{r:04x}{g:04x}{b:04x}")
+else:
+ print("Could not determine foreground color")
+
+# Get background color
+r, g, b = term.get_bgcolor()
+if (r, g, b) != (-1, -1, -1):
+ print(f"Background color: RGB({r}, {g}, {b})")
+ print(f" Hex: #{r:04x}{g:04x}{b:04x}")
+else:
+ print("Could not determine background color")

bin/dec_modes_query.py

@@ -5,7 +5,7 @@
 
 # Query mouse support
 mode = term.DecPrivateMode(term.DecPrivateMode.MOUSE_REPORT_CLICK)
-response = term.get_dec_mode(mode, timeout=1)
+response = term.get_dec_mode(mode)
 
 print(f"Checking {mode.name} (mode {mode.value}) {mode.long_description}: ", end="")
 

bin/detect-multibyte.py

@@ -48,7 +48,7 @@ def get_pos(term):
  # Invalid variable name "Position"
  Position = collections.namedtuple('Position', ('row', 'column'))
 
- pos = Position(*term.get_location(timeout=5.0))
+ pos = Position(*term.get_location())
 
  if -1 in pos:
  print('stdin: not a human', file=sys.stderr)

bin/display-modes.py

@@ -89,7 +89,7 @@ def display_dec_modes(term):
  # Query each mode
  for idx, (mode_name, mode_code) in enumerate(sorted(all_modes.items(), key=lambda x: x[1])):
  print(f' Testing {mode_name}...' + term.clear_eol, end='\r', flush=True)
- response = term.get_dec_mode(mode_code, timeout=0.1, force=force_mode)
+ response = term.get_dec_mode(mode_code, force=force_mode)
  if response.supported:
  supported_modes[mode_name] = response
 

bin/resize.py

@@ -66,7 +66,7 @@ def main():
  # to the farthest lower-right corner. By requesting the current
  # position, we may negotiate about the window size directly with the
  # terminal emulator connected at the distant end.
- pos = Position(*term.get_location(timeout=5.0))
+ pos = Position(*term.get_location())
 
  if -1 not in pos:
  # true size was determined

blessed/terminal.py

@@ -721,7 +721,7 @@ def location(self, x: Optional[int] = None, y: Optional[int]
  self.stream.write(self.restore)
  self.stream.flush()
 
- def get_location(self, timeout: Optional[float] = None) -> Tuple[int, int]:
+ def get_location(self, timeout: float = 1) -> Tuple[int, int]:
  r"""
  Return tuple (row, column) of cursor position.
 
@@ -798,7 +798,7 @@ def get_location(self, timeout: Optional[float] = None) -> Tuple[int, int]:
  # rather than crowbarring such logic into an exception handler.
  return -1, -1
 
- def get_fgcolor(self, timeout: Optional[float] = None) -> Tuple[int, int, int]:
+ def get_fgcolor(self, timeout: float = 1) -> Tuple[int, int, int]:
  """
  Return tuple (r, g, b) of foreground color.
 
@@ -813,11 +813,13 @@ def get_fgcolor(self, timeout: Optional[float] = None) -> Tuple[int, int, int]:
 
  The foreground color is determined by emitting an `OSC 10 color query
  <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`_.
+
+ See also :meth:`~.Terminal.get_bgcolor` for querying the background color.
  """
  match = self._query_response('\x1b]10;?\x07', RE_GET_FGCOLOR_RESPONSE, timeout)
  return tuple(int(val, 16) for val in match.groups()) if match else (-1, -1, -1)
 
- def get_bgcolor(self, timeout: Optional[float] = None) -> Tuple[int, int, int]:
+ def get_bgcolor(self, timeout: float = 1) -> Tuple[int, int, int]:
  """
  Return tuple (r, g, b) of background color.
 
@@ -832,6 +834,8 @@ def get_bgcolor(self, timeout: Optional[float] = None) -> Tuple[int, int, int]:
 
  The background color is determined by emitting an `OSC 11 color query
  <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`_.
+
+ See also :meth:`~.Terminal.get_fgcolor` for querying the foreground color.
  """
  match = self._query_response('\x1b]11;?\x07', RE_GET_BGCOLOR_RESPONSE, timeout)
  return tuple(int(val, 16) for val in match.groups()) if match else (-1, -1, -1)
@@ -976,7 +980,7 @@ def does_sixel(self, timeout: Optional[float] = 1.0, force: bool = False) -> boo
  return da.supports_sixel if da is not None else False
 
  def get_dec_mode(self, mode: Union[int, _DecPrivateMode],
- timeout: Optional[float] = None, force: bool = False) -> DecModeResponse:
+ timeout: float = 1.0, force: bool = False) -> DecModeResponse:
  """
  Query the state of a DEC Private Mode (DECRQM).
 
@@ -1005,7 +1009,7 @@ def get_dec_mode(self, mode: Union[int, _DecPrivateMode],
  re-inquiry unless ``force=True``. Although there are special cases
  where a user may re-configure their terminal settings after the state
  was requested by an application, the application is generally restarted
- to recognize the new settings rather than to repeatidly re-inquire about
+ to recognize the new settings rather than to repeatedly re-inquire about
  their latest value!
 
  :arg mode: DEC Private Mode to query

docs/colors.rst

@@ -51,6 +51,19 @@ color!
 
 .. include:: all_the_colors.txt
 
+Querying Terminal Colors
+-------------------------
+
+You can query the terminal's current foreground and background colors using
+:meth:`~.Terminal.get_fgcolor` and :meth:`~.Terminal.get_bgcolor`. These methods return RGB tuples
+that represent the actual colors configured in the terminal emulator:
+
+.. literalinclude:: ../bin/color_query.py
+ :language: python
+
+These methods are useful for adapting your application's color scheme to match the user's terminal
+theme, or for detecting whether the terminal has a light or dark background.
+
 256 Colors
 ----------
 

docs/location.rst

@@ -90,7 +90,7 @@ This uses a kind of "answer back" sequence that your terminal emulator responds
 terminal may not respond, or may take some time to respond, the :paramref:`~.get_location.timeout`
 keyword argument can be specified to return coordinates (-1, -1) after a blocking timeout:
 
- >>> term.get_location(timeout=5)
+ >>> term.get_location()
  (32, 0)
 
 The return value of :meth:`~.Terminal.get_location` mirrors the arguments of