Pager Class Reference

Public Member Functions
	__init__ (self, prompt=None, quit_if_one_screen=False)
	__enter__ (self)
	__exit__ (self, exc_type, exc_val, exc_tb)

Protected Attributes
str	_pager = os.environ.get("PAGER", "less")
	pager program to use
str	_prompt = prompt
	prompt string
	_quit_if_one_screen = quit_if_one_screen
	flag indicating whether the pager should automatically exit if the content fits on one screen
	_pager_process = None
	Pager subprocess.
	_original_stdout_fd = None
	Original file descriptor for stdout before entering the context.
	_original_stderr_fd = None
	Original file descriptor for stderr before entering the context.
	_original_stdout = None
	Original sys.__stdout__ before entering the context.
	_original_stderr = None
	Original sys.__stderr__ before entering the context.
	_original_stdout_isatty = None
	Original sys.stdout.isatty.
	_original_stderr_isatty = None
	Original sys.stderr.isatty.

Detailed Description

Context manager providing page-wise output using ``less``, similar to how
git handles long output of for example ``git diff``.  Paging will only be
active if the output is to a terminal and not piped into a file or to a
different program.

Warning:
    To be able to see `basf2` log messages like `B2INFO() <basf2.B2INFO>`
    on the paged output you have to set
    `basf2.logging.enable_python_logging = True
    <basf2.LogPythonInterface.enable_python_logging>`

.. versionchanged:: release-03-00-00
   the pager no longer waits until all output is complete but can
   incrementally show output. It can also show output generated in C++

You can set the environment variable ``$PAGER`` to an empty string or to
``cat`` to disable paging or to a different program (for example ``more``)
which should retrieve the output and display it.

>>> with Pager():
>>>     for i in range(30):
>>>         print("This is an example on how to use the pager.")

Parameters:
    prompt (str): a string argument allows overriding the description
        provided by ``less``. Special characters may need escaping.
        Will only be shown if paging is used and the pager is actually ``less``.
    quit_if_one_screen (bool): indicating whether the Pager should quit
        automatically if the content fits on one screen. This implies that
        the content stays visible on pager exit. True is similar to the
        behavior of :program:`git diff`, False is similar to :program:`git
        --help`

Definition at line 159 of file terminal_utils.py.

Constructor & Destructor Documentation

__init__()

__init__	(		self,
			prompt = None,
			quit_if_one_screen = False )

 constructor just remembering the arguments 

Definition at line 195 of file terminal_utils.py.

    def __init__(self, prompt=None, quit_if_one_screen=False):
        """ constructor just remembering the arguments """
        
        self._pager = os.environ.get("PAGER", "less")
        # treat "cat" as no pager at all
        if self._pager == "cat":
            self._pager = ""
        
        self._prompt = prompt
        
        self._quit_if_one_screen = quit_if_one_screen
        
        self._pager_process = None
        
        self._original_stdout_fd = None
        
        self._original_stderr_fd = None
        
        self._original_stdout = None
        
        self._original_stderr = None
        
        self._original_stdout_isatty = None
        
        self._original_stderr_isatty = None
 

Member Function Documentation

__enter__()

__enter__

(

self

)

 entering context 

Definition at line 222 of file terminal_utils.py.

    def __enter__(self):
        """ entering context """
        if not sys.stdout.isatty() or self._pager == "":
            return
 
        # save old sys.__stderr__ and sys.__stdout__ objects
        self._original_stderr = sys.__stderr__
        self._original_stderr = sys.__stdout__
        try:
            # and duplicate the current output file descriptors
            self._original_stdout_fd = os.dup(sys.stdout.fileno())
            self._original_stderr_fd = os.dup(sys.stderr.fileno())
        except AttributeError:
            # jupyter notebook stdout/stderr objects don't have a fileno so
            # don't support paging
            return
 
        # This is a bit annoying: Usually in python the sys.__stdout__ and
        # sys.__stderr__ objects point to the original stdout/stderr on program start.
        #
        # However we modify the file descriptors directly so these objects will
        # also be redirected automatically. The documentation for
        # sys.__stdout__ says it "could be useful to print to the actual
        # standard stream no matter if the sys.std* object has been
        # redirected". Also,  querying the terminal size looks at
        # sys.__stdout__ which would no longer be pointing to a tty.
        #
        # So lets provide objects pointing to the original file descriptors so
        # that they behave as expected, i.e. as if we would only have
        # redirected sys.stdout and sys.stderr ...
        sys.__stdout__ = io.TextIOWrapper(os.fdopen(self._original_stdout_fd, "wb"))
        sys.__stderr__ = io.TextIOWrapper(os.fdopen(self._original_stderr_fd, "wb"))
 
        # also monkey patch the isatty() function of stdout to actually keep
        # returning True even if we moved the file descriptor
        self._original_stdout_isatty = sys.stdout.isatty
        sys.stdout.isatty = lambda: True
        self._original_stderr_isatty = sys.stderr.isatty
        sys.stderr.isatty = lambda: True
 
        # fine, everything is saved, start the pager
        pager_cmd = [self._pager]
        if self._pager == "less":
            if self._prompt is None:
                self._prompt = ''  # same as default prompt
            self._prompt += ' (press h for help or q to quit)'
            pager_cmd += ['-R', '-Ps' + self._prompt.strip()]
            if self._quit_if_one_screen:
                pager_cmd += ['-F', '-X']
        self._pager_process = subprocess.Popen(pager_cmd + ["-"], restore_signals=True,
                                               stdin=subprocess.PIPE)
        # and attach stdout to the pager stdin
        pipe_fd = self._pager_process.stdin.fileno()
        # and if stderr was a tty do the same for stderr
        os.dup2(pipe_fd, sys.stdout.fileno())
        if sys.stderr.isatty():
            os.dup2(pipe_fd, sys.stderr.fileno())
 

__exit__()

__exit__	(		self,
			exc_type,
			exc_val,
			exc_tb )

 exiting context 

Definition at line 280 of file terminal_utils.py.

    def __exit__(self, exc_type, exc_val, exc_tb):
        """ exiting context """
        # no pager, nothing to do
        if self._pager_process is None:
            return
 
        # otherwise let's try to flush whatever is left
        try:
            sys.stdout.flush()
        except BrokenPipeError:
            # apparently pager died before we could flush ... so let's move the
            # remaining output to /dev/null and flush whatever is left
            devnull = os.open(os.devnull, os.O_WRONLY)
            os.dup2(devnull, sys.stdout.fileno())
            sys.stdout.flush()
 
        # restore output
        os.dup2(self._original_stdout_fd, sys.stdout.fileno())
        os.dup2(self._original_stderr_fd, sys.stderr.fileno())
        # and the original __stdout__/__stderr__ object just in case. Will also
        # close the copied file descriptors
        sys.__stdout__.close()
        sys.__stderr__.close()
        sys.__stderr__ = self._original_stderr
        sys.__stdout__ = self._original_stdout
        # and clean up our monkey patch of isatty
        sys.stdout.isatty = self._original_stdout_isatty
        sys.stderr.isatty = self._original_stderr_isatty
 
        # wait for pager
        self._pager_process.communicate()
 
        # and if we exited due to broken pipe ... then ignore it
        return exc_type == BrokenPipeError
 
 

Member Data Documentation

_original_stderr

_original_stderr = None

protected

Original sys.__stderr__ before entering the context.

Definition at line 216 of file terminal_utils.py.

_original_stderr_fd

_original_stderr_fd = None

protected

Original file descriptor for stderr before entering the context.

Definition at line 212 of file terminal_utils.py.

_original_stderr_isatty

_original_stderr_isatty = None

protected

Original sys.stderr.isatty.

Definition at line 220 of file terminal_utils.py.

_original_stdout

_original_stdout = None

protected

Original sys.__stdout__ before entering the context.

Definition at line 214 of file terminal_utils.py.

_original_stdout_fd

_original_stdout_fd = None

protected

Original file descriptor for stdout before entering the context.

Definition at line 210 of file terminal_utils.py.

_original_stdout_isatty

_original_stdout_isatty = None

protected

Original sys.stdout.isatty.

Definition at line 218 of file terminal_utils.py.

_pager

str _pager = os.environ.get("PAGER", "less")

protected

pager program to use

Definition at line 198 of file terminal_utils.py.

_pager_process

_pager_process = None

protected

Pager subprocess.

Definition at line 208 of file terminal_utils.py.

_prompt

str _prompt = prompt

protected

prompt string

Definition at line 203 of file terminal_utils.py.

_quit_if_one_screen

_quit_if_one_screen = quit_if_one_screen

protected

flag indicating whether the pager should automatically exit if the content fits on one screen

Definition at line 206 of file terminal_utils.py.

---

The documentation for this class was generated from the following file:

• framework/scripts/terminal_utils.py