Metadata-Version: 2.1
Name: cs.upd
Version: 20200613
Summary: Single and multiple line status updates with minimal update sequences.
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: cs@cskk.id.au
License: GNU General Public License v3 or later (GPLv3+)
Description: Single and multiple line status updates with minimal update sequences.
        
        *Latest release 20200613*:
        * New UpdProxy.__call__ which sets the .text property in the manner of logging calls, with (msg,*a).
        * New Upd.normalise static method exposing the text normalisation `unctrl(text.rstrip())`.
        * New UpdProxy.prefix attribute with a fixed prefix for status updates; `prefix+text` is left cropped for display purposes when updated.
        * New UpdProxy.width property computing the space available after the prefix, useful for sizing things like progress bars.
        * Make UpdProxy a context manager which self deletes on exit.
        * Upd: make default backend=sys.stderr, eases the common case.
        * New Upd.above() context manager to support interleaving another stream with the output, as when stdout (for print) is using the same terminal as stderr (for Upd).
        * New out() top level function for convenience use with the default Upd().
        * New nl() top level function for writing a line to stderr.
        * New print() top level function wrapping the builtin print; callers can use "from cs.upd import print" to easily interleave print() with cs.upd use.
        
        This is available as an output mode in `cs.logutils`.
        
        Single line example:
        
            from cs.upd import Upd, nl, print
            .....
            with Upd() as U:
                for filename in filenames:
                    U.out(filename)
                    ... process filename ...
                    U.nl('an informational line to stderr')
                    print('a line to stdout')
        
        Multiline multithread example:
        
            from threading import Thread
            from cs.upd import Upd, print
            .....
            def runner(filename, proxy):
                # initial status message
                proxy.text = "process %r" % filename
                ... at various points:
                    # update the status message with current progress
                    proxy.text = '%r: progress status here' % filename
                # completed, remove the status message
                proxy.close()
                # print completion message to stdout
                print("completed", filename)
            .....
            with Upd() as U:
                U.out("process files: %r", filenames)
                Ts = []
                for filename in filenames:
                    proxy = U.insert(1) # allocate an additional status line
                    T = Thread(
                        "process "+filename,
                        target=runner,
                        args=(filename, proxy))
                    Ts.append(T)
                    T.start()
                for T in Ts:
                    T.join()
        
        ## Function `cleanupAtExit()`
        
        Cleanup function called at programme exit to clear the status line.
        
        ## Function `nl(msg, *a, **kw)`
        
        Write `msg` to `file` (default `sys.stdout`),
        without interfering with the `Upd` instance.
        This is a thin shim for `Upd.print`.
        
        ## Function `out(msg, *a, **outkw)`
        
        Update the status line of the default `Upd` instance.
        Parameters are as for `Upd.out()`.
        
        ## Function `print(*a, **kw)`
        
        Wrapper for the builtin print function
        to call it inside `Upd.above()` and enforce a flush.
        
        The function supports an addition parameter beyond the builtin print:
        * `upd`: the `Upd` instance to use, default `Upd()`
        
        Programmes intregrating `cs.upd` with use of the builtin `print`
        function should use this as import time:
        
            from cs.upd import print
        
        ## Class `Upd(cs.obj.SingletonMixin)`
        
        A `SingletonMixin` subclass for maintaining a regularly updated status line.
        
        The default backend is `sys.stderr`.
        
        ## Class `UpdProxy`
        
        A proxy for a status line of a multiline `Upd`.
        
        This provides a stable reference to a status line after it has been
        instantiated by `Upd.insert`.
        
        The status line can be accessed and set via the `.text` property.
        
        An `UpdProxy` is also a context manager which self deletes on exit:
        
            U = Upd()
            ....
            with U.insert(1, 'hello!') as proxy:
                .... set proxy.text as needed ...
            # proxy now removed
        
        # Release Log
        
        
        
        *Release 20200613*:
        * New UpdProxy.__call__ which sets the .text property in the manner of logging calls, with (msg,*a).
        * New Upd.normalise static method exposing the text normalisation `unctrl(text.rstrip())`.
        * New UpdProxy.prefix attribute with a fixed prefix for status updates; `prefix+text` is left cropped for display purposes when updated.
        * New UpdProxy.width property computing the space available after the prefix, useful for sizing things like progress bars.
        * Make UpdProxy a context manager which self deletes on exit.
        * Upd: make default backend=sys.stderr, eases the common case.
        * New Upd.above() context manager to support interleaving another stream with the output, as when stdout (for print) is using the same terminal as stderr (for Upd).
        * New out() top level function for convenience use with the default Upd().
        * New nl() top level function for writing a line to stderr.
        * New print() top level function wrapping the builtin print; callers can use "from cs.upd import print" to easily interleave print() with cs.upd use.
        
        *Release 20200517*:
        * Multiline support!
        * Multiline support!
        * Multiline support!
        * New UpdProxy class to track a status line of a multiline Upd in the face of further inserts and deletes.
        * Upd(...) now returns a context manager to clean up the display on its exit.
        * Upd(...) is now a SingletonMixin in order to use the same state if set up in multiple places.
        
        *Release 20200229*:
        * Upd: can now be used as a context manager, clearing the line on exit.
        * Upd.without is now a context manager, returning the older state, and accepting an optional inner state (default "").
        * Upd is now a singleton factory, obsoleting upd_for.
        * Upd.nl: use "insert line above" mode if supported.
        
        *Release 20181108*:
        Documentation improvements.
        
        *Release 20170903*:
        * New function upd_for(stream) returning singleton Upds.
        * Drop noStrip keyword argument/mode - always strip trailing whitespace.
        
        *Release 20160828*:
        * Use "install_requires" instead of "requires" in DISTINFO.
        * Add Upd.flush method.
        * Upd.out: fix longstanding trailing text erasure bug.
        * Upd.nl,out: accept optional positional parameters, use with %-formatting if supplied, just like logging.
        
        *Release 20150118*:
        metadata fix
        
        *Release 20150116*:
        Initial PyPI release.
Keywords: python2,python3
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Description-Content-Type: text/markdown
