Metadata-Version: 2.1
Name: tiotrap
Version: 0.3.2
Summary: Helper For Capturing Text IO Streams like stdout, stderr
Home-page: https://pypi.org/project/tiotrap/
Author: Timothy C Quinn
Author-email: tim.c.quinn@gmail.com
License: BSD-3-Clause
Description: ## tiotrap
        
        Simple class for trapping / capturing Python Text IO streams like from `subprocess.popen`, `pexpect`, `sys.stderr` and others; enabling the capture output of or dropping streams with cross platform `DEVNULL` helper. 
        
        ### Installation
        
        ```
        python3 -m pip install tiotrap
        ```
        
        
        ### Usage
        
        This tool contains one class `TextIOTrap` and a helper `DEVNULL`.
        
        
        ### Examples
        
        #### (Ex1) Use `TextIOTrap` to capture stdout of a chatty process using `store` option:
        ```python3
        _stdout_bk = sys.stdout # Store original stdout
        ttrap = tiotrap.TextIOTrap(store=True)
        
        try:
            sys.stdout = ttrap # Map stdout to tiotrap
            print("TEST1")
            # call some chatty functions()
            print("TEST2")
        
        finally:
            sys.stdout = _stdout_bk # Restore stdout
        ```
        Output of print:
        ```
        captured logs:
        TEST1
        <chatty outputs here>
        TEST2
        ```
        
        
        #### (Ex2) Use `TextIOTrap` to capture stdout using `write_handler` option:
        ```python3
        aTrap = []
        _stdout_bk = sys.stdout
        try:
            sys.stdout = tiotrap.TextIOTrap(write_handler=lambda s: aTrap.append(s))
            print("TEST1")
            print("TEST2")
        
        finally:
            sys.stdout = _stdout_bk
        # print adds extra \n end so remove with rstrip()
        print(f"aTrap:\n{''.join(aTrap).rstrip()}\n~end~\n")
        ```
        
        Output of print:
        ```
        aTrappedStdout = ['TEST1', 'TEST2']
        ```
        You can substitute lambda with a function or method call to handle `writes` with your own code.
        
        
        
        #### (Ex3) Use `TextIOTrap` grab output `pexpect` call :
        ```python3
        ttrap = tiotrap.TextIOTrap(store=True)
        
        p = pexpect.spawn('ls -la')
        p.logfile = ttrap
        p.expect(pexpect.EOF)
        
        print(f"`ls -la` cmd output:\n{ttrap.entries()}\n~")
        ```
        
        Output of print:
        ```
        ls output:
        <full directory listing here of cwd>
        ```
        
        Other uses of `TextIOTrap`:
        * Output the stdout of a `subprocess.popen` call in real time to a secondary log file
        * ...
        
        
        #### (Ex4) Use `TextIOTrap` grab output `pexpect` call :
        ```python3
        ttrap = tiotrap.TextIOTrap(store=True)
        
        p = pexpect.spawn('ls -la')
        p.logfile = ttrap
        p.expect(pexpect.EOF)
        
        print("ls -la` cmd output (as was written):")
        for write in ttrap:
            print(write)
        ```
        Output: Similar to Ex4
        
        
        #### (Ex5) Use `DEVNULL` to drop all output of a TextIO Stream
        ```python3
        _stdout_bk = sys.stdout
        
        try:
            sys.stdout = tiotrap.DEVNULL
            print("THIS WILL NOT PRINT")
        
        finally:
            sys.stdout = _stdout_bk
        
        print("THIS WILL PRINT")
        ```
        This DEVNULL is very simple implementation and is fully cross platform unlike someother DEVNULL implementations.
        
        
        Note:` TextIOTrap` has been set up to be compatible with the standard methods for a Text IO streams. I'll be glad to update if any edge cases are discovered.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
