Single and multiple line status updates with minimal update sequences.
*Latest release 20240412*:
* Upd.run_task: provide the label as the new UpdProxy prefix.
* Upd.insert: the supplied txt is the proxy.text, not the prefix.
* UpdProxy.text: setting to None sets to self._text_auto() if present or makes no change.
* New @without decorator to withdraw the Upd during a function.
* print: use the builtin print directly if the Upd is disabled.
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()
## A note about Upd and terminals
I routinely use an `Upd()` as a progress reporting tool for commands
running on a terminal. This attaches to `sys.stderr` by default.
However, it is usually not desirable to run an `Upd` display
if the backend is not a tty/terminal.
Therefore, an `Upd` has a "disabled" mode
which performs no output;
the default behaviour is that this mode activates
if the backend is not a tty (as tested by `backend.isatty()`).
The constructor has an optional parameter `disabled` to override
this default behaviour.
## Function `demo()`
A tiny demo function for visual checking of the basic functionality.
## Function `nl(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1113604c0>, **kw)`
Write `msg` to `file` (default `sys.stdout`),
without interfering with the `Upd` instance.
This is a thin shim for `Upd.print`.
## Function `out(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x11135ba30>, **kw)`
Update the status line of the default `Upd` instance.
Parameters are as for `Upd.out()`.
## Function `pfxprint(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x11135bf40>, **kw)`
Wrapper for `cs.pfx.pfxprint` to pass `print_func=cs.upd.print`.
Programmes integrating `cs.upd` with use of the `cs.pfx.pfxprint`
function should use this at import time:
from cs.upd import pfxprint
## Function `run_task(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1113601f0>, **kw)`
Top level `run_task` function to call `Upd.run_task`.
## Class `Upd(cs.obj.SingletonMixin, cs.resources.MultiOpenMixin, cs.threads.HasThreadState)`
A `SingletonMixin` subclass for maintaining multiple status lines.
The default backend is `sys.stderr`.
*Method `Upd.__init__(self, backend=None, columns=None, disabled=None)`*:
Initialise the `Upd`.
Parameters:
* `backend`: the output file, default from the environment
variable `$CS_UPD_BACKEND` otherwise `sys.stderr`
* `columns`: the width of the output,
default from the width of the `backend` tty if it is a tty,
`80` otherwise
* `disabled`: if true, disable the output - just keep state;
default true if the output is not a tty;
this automatically silences the `Upd` if stderr is not a tty
*Method `Upd.__enter_exit__(self)`*:
Generator supporting `__enter__` and `__exit__`.
On shutdown, if we are exiting because of an exception
which is not a `SystemExit` with a `code` of `None` or `0`
then we preserve the status lines one screen.
Otherwise we clean up the status lines.
*Method `Upd.__getitem__(self, index)`*:
The text of the status line at `index`.
*Method `Upd.__len__(self)`*:
The length of an `Upd` is the number of slots.
*Method `Upd.above(self, need_newline=False)`*:
Context manager to move to the top line of the `Upd` display,
clear it, `yield`, redraw below.
This context manager is for use when interleaving _another_
stream with the `Upd` display;
if you just want to write lines above the display
for the same backend use `Upd.nl`.
The usual situation for `Upd.above`
is interleaving `sys.stdout` and `sys.stderr`,
which are often attached to the same terminal.
Note that the caller's output should be flushed
before exiting the suite
so that the output is completed before the `Upd` resumes.
Example:
U = Upd() # default sys.stderr Upd
......
with U.above():
print('some message for stdout ...', flush=True)
*Method `Upd.cursor_invisible(self)`*:
Make the cursor vinisible.
*Method `Upd.cursor_visible(self)`*:
Make the cursor visible.
*Method `Upd.delete(self, index)`*:
Delete the status line at `index`.
Return the `UpdProxy` of the deleted status line.
*Method `Upd.diff(oldtxt, newtxt, columns, raw_text=False)`*:
Compute the text sequences required to update `oldtxt` to `newtxt`
presuming the cursor is at the right hand end of `oldtxt`.
The available area is specified by `columns`.
We normalise `newtxt` as using `self.normalise`.
`oldtxt` is presumed to be already normalised.
If `raw_text` is true (default `False`) we do not normalise `newtxt`
before comparison.
*Method `Upd.disable(self)`*:
Disable updates.
*Property `Upd.disabled`*:
Whether this `Upd` is currently disabled.
*Method `Upd.enable(self)`*:
Enable updates.
*Method `Upd.flush(self)`*:
Flush the backend stream.
*Method `Upd.insert(self, index, txt='', proxy=None, **proxy_kw) -> 'UpdProxy'`*:
Insert a new status line at `index`.
Return the `UpdProxy` for the new status line.
*Method `Upd.nl(self, txt, *a, redraw=False)`*:
Write `txt` to the backend followed by a newline.
Parameters:
* `txt`: the message to write.
* `a`: optional positional parameters;
if not empty, `txt` is percent formatted against this list.
* `redraw`: if true (default `False`) use the "redraw" method.
This uses one of two methods:
* insert above:
insert a line above the top status line and write the message there.
* redraw:
clear the top slot, write txt and a newline,
redraw all the slots below.
The latter method is used if `redraw` is true
or if `txt` is wider than `self.columns`
or if there is no "insert line" capability.
*Method `Upd.normalise(txt)`*:
Normalise `txt` for display,
currently implemented as:
`unctrl(txt.rstrip())`.
*Method `Upd.out(self, txt, *a, slot=0, raw_text=False, redraw=False) -> str`*:
Update the status line at `slot` to `txt`.
Return the previous status line content.
Parameters:
* `txt`: the status line text.
* `a`: optional positional parameters;
if not empty, `txt` is percent formatted against this list.
* `slot`: which slot to update; default is `0`, the bottom slot
* `raw_text`: if true (default `False`), do not normalise the text
* `redraw`: if true (default `False`), redraw the whole line
instead of doing the minimal and less visually annoying
incremental change
*`Upd.perthread_state`*
*Method `Upd.proxy(self, index)`*:
Return the `UpdProxy` for `index`.
Returns `None` if `index` is out of range.
The index `0` is never out of range;
it will be autocreated if there are no slots yet.
*Method `Upd.run_task(self, label: str, *, report_print=False, tick_delay: int = 0.3, tick_chars='|/-\\')`*:
Context manager to display an `UpdProxy` for the duration of some task.
It yields the proxy.
*Method `Upd.selfcheck(self)`*:
Sanity check the internal data structures.
Warning: this uses asserts.
*Method `Upd.shutdown(self, preserve_display=False)`*:
Clean out this `Upd`, optionally preserving the displayed status lines.
*Method `Upd.ti_str(self, ti_name)`*:
Fetch the terminfo capability string named `ti_name`.
Return the string or `None` if not available.
*Method `Upd.without(self, temp_state='', slot=0)`*:
Context manager to clear the status line around a suite.
Returns the status line text as it was outside the suite.
The `temp_state` parameter may be used to set the inner status line
content if a value other than `''` is desired.
## 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
*Method `UpdProxy.__init__(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x111360790>, **kw)`*:
Initialise a new `UpdProxy` status line.
Parameters:
* `index`: optional position for the new proxy as for `Upd.insert`,
default `1` (directly above the bottom status line)
* `upd`: the `Upd` instance with which to associate this proxy,
default the default `Upd` instance (associated with `sys.stderr`)
* `text`: optional initial text for the new status line
*Method `UpdProxy.__call__(self, msg, *a)`*:
Calling the proxy sets its `.text` property
in the form used by other messages: `(msg,*a)`
*Method `UpdProxy.__del__(self)`*:
Delete this proxy from its parent `Upd`.
*Method `UpdProxy.delete(self)`*:
Delete this proxy from its parent `Upd`.
*Method `UpdProxy.extend_prefix(self, more_prefix, print_elapsed=False)`*:
Context manager to append text to the prefix.
*Method `UpdProxy.insert(self, index, txt='')`*:
Insert a new `UpdProxy` at a position relative to this `UpdProxy`.
Return the new proxy.
This supports the positioning of related status lines.
*Property `UpdProxy.prefix`*:
The current prefix string.
*Method `UpdProxy.reset(self)`*:
Clear the proxy: set both the prefix and text to `''`.
*Property `UpdProxy.suffix`*:
The current suffix string.
*Property `UpdProxy.text`*:
The text of this proxy's slot, without the prefix.
*Property `UpdProxy.width`*:
The available space for text after `self.prefix` and before `self.suffix`.
This is available width for uncropped text,
intended to support presizing messages such as progress bars.
Setting the text to something longer will crop the rightmost
portion of the text which fits.
## Function `uses_upd(*da, **dkw)`
Decorator for functions accepting an optional `upd:Upd` parameter,
default from `Upd.default() or Upd()`.
This also makes the `upd` the default `Upd` instance for this thread.
## Function `with_upd_proxy(*da, **dkw)`
Decorator to run `func` with an additional parameter `upd_proxy`
being an `UpdProxy` for progress reporting.
Example:
@with_upd_proxy
def func(*a, upd_proxy:UpdProxy, **kw):
... perform task, updating upd_proxy ...
## Function `without(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1113613f0>, **kw)`
Context manager withdraw the `Upd` while something runs.
Example:
from cs.upd import without
...
with without():
os.system('ls -la')
# Release Log
*Release 20240412*:
* Upd.run_task: provide the label as the new UpdProxy prefix.
* Upd.insert: the supplied txt is the proxy.text, not the prefix.
* UpdProxy.text: setting to None sets to self._text_auto() if present or makes no change.
* New @without decorator to withdraw the Upd during a function.
* print: use the builtin print directly if the Upd is disabled.
*Release 20240316*:
Fixed release upload artifacts.
*Release 20240216*:
New without() context manager to withdraw the Upd while something runs.
*Release 20240201*:
* Upd.run_task: the label is now the only positional parameter.
* @uses_upd: use @decorator to extract the inner function docstring etc.
*Release 20231129*:
Small changes.
*Release 20230401*:
* Upd.run_task: use a local RunState to control the ticker, drop `runstate` parameter.
* Renamed default HasThreadState.THREAD_STATE_ATTR to 'perthread_state'.
* Keep a module level name for the default Upd instance.
* Upd.shutdown: cope with shutdown early enough that there's no self._lock.
* Honour new $CS_UPD_BACKEND envvar to support eg defaulting Upd to /dev/null.
*Release 20230217*:
* @uses_upd: provide Upd() if there is no current default.
* @uses_upd: set the default Upd to the chosen Upd instance.
* Upd: subclass MultiOpenMixin, drop close() and closed() methods; always make a default Upd instance in open state.
* Upd: always define an initial slot and its UpdProxy, avoids a billion special cases elsewhere.
* UpdProxy: accept index=None as "make a bare UpdProxy for upd" used in the Upd._reset setup code, reserving the magic self inserting mode for when index is not None.
*Release 20230212*:
* BREAKING: replace @upd_proxy (which fiddled upd.state) with @with_upd_proxy which supplies an upd_proxy parameter.
* UpdProxy.text: bugfix spelling of _text_auto.
* Upd now subclasses HasThreadState, replace global "state" with "Upd.state", related adjustments.
* UpdProxy: new optional update_period parameter to limit the update frequency based on the time since last update.
* Upd.insert: support keyword parameters for the created UpdProxy.
*Release 20221228*:
Bugfix print: plumb the end= parameter.
*Release 20220918*:
* DROPPING PYTHON 2 SUPPORT.
* New @uses_upd decorator for things accepting an optional upd=Upd().
* UpdProxy.__init__: use @uses_upd, make text the only optional positional parameter.
* New top level `run_task` context manager wrapping `Upd.run_task`.
* Make all the top level functions accept an optional upd=Upd() parameter.
* Upd.run_task: wrap the yield in a try/finally to manage the RunState.
* Upd.run_task: set default tick_delay=0.3, 0.15 was too fast.
* UpdProxy: new optional text_auto() callable parameter, used to compute proxy.text if proxy._text is empty.
* UpdProxy.width: account for the suffix.
*Release 20220619*:
Upd.cursor_visible,cursor_invisible: actually send the escape sequence.
*Release 20220606*:
Upd.insert: insert(1) on empty slots autocreates slot 0.
*Release 20220605*:
* New Upd.run_task to add a status line for the duration of some task.
* UpdProxy.extend_prefix: new optional print_elapsed parameter.
*Release 20220530*:
* UpdProxy: new .suffix property.
* Upd: new run_task context manager to display an UpdProxy while something runs, with optional ticker.
* Small bugfix.
*Release 20220504*:
* Upd.above: do a disable/enable around the yield, use try/finally for reliability.
* Upd.delete: just warn about index out of range, seems it can happen during interpreter shutdown; to be debugged later.
*Release 20220429*:
* UpdProxy: accept optional prefix= parameter.
* New pfxprint wrapper for cs.pfx.pfxprint, like the print wrapper.
*Release 20210717*:
Docstring update.
*Release 20210507*:
Upgrade dependency on cs.context for StackableState.
*Release 20210428.4*:
Another dummy release during debugging.
*Release 20210428.3*:
Repeat the previous release, again again.
*Release 20210428.2*:
Repeat the previous release, again.
*Release 20210428.1*:
Repeat the previous release.
*Release 20210428*:
Do curses.setupterm() during iinit, avoid failure when stdout is not a tty.
*Release 20210316*:
* New UpdProxy.extend_prefix context manager to extend the proxy prefix around a suite.
* New global "state" StackableStatei object with an automatic .upd attribute.
* New @upd_proxy decorator to create an UpdProxy for the duration of a function call and record it as state.proxy.
* Bugfix Upd.insert: add slots.insert and proxies.insert missing from the no-display path.
* Rename private method Upd._adjust_text_v to public method Upd.diff.
*Release 20210122*:
* Autocreate slot 0 on first use.
* Reliable cleanup at exit.
* Fix a display small display issue.
*Release 20201202*:
* Fix for batch mode - handle failure of curses.setupterm(), throws TypeError.
* Upd.insert: defer check for cuu1 capability until there's at least one line already.
*Release 20201102*:
* Upd.nl: simple approach when there are no status lines.
* Upd: new cursor_visible and cursor_invisible methods to show and hide the cursor.
*Release 20201026.1*:
Bugfix Upd.nl: simple output if there are no status lines to accomodate.
*Release 20201026*:
Bugfix Upd.insert: accept insert(1) when len(self)==0.
*Release 20201025*:
* Upd: new .disabled property to allow inspection of disabledness.
* Upd.insert: accept negative insert indices to position from the top of the list.
* Upd.nl: use clear-to-end-of-line at the end of the message if available.
* UpdProxy: turn .prefix into a property which causes a redraw when changed.
* Upd.proxy(index): return None if the index is out of range, accomodates racy or incorrect behaviour by a user.
* UpdProxy: cropped overflowing text gets a leading '<' to make it apparent.
* UpdProxy: new .insert() method to support insterting new proxies with respect to an existing proxy.
* UpdProxy: new reset() method, clears prefix and text.
* UpdProxy.__init__: BREAKING: make all arguments optional to aid use.
* Upd: do not make any slots unless required.
* Make the compute-redraw-strings methods private.
*Release 20200914*:
Bugfix UpdProxy.__enter__: return self.
*Release 20200716.1*:
DISTINFO: make the cs.obj requirement more specific due to the SingletonMixin API change.
*Release 20200716*:
Update for changed cs.obj.SingletonMixin API.
*Release 20200626.1*:
Upd.__exit__: bugfix test of SystemExit exceptions.
*Release 20200626*:
* UpdProxy: call self.delete on __del__.
* If self._backend is None act as if disabled, occurs during shutdown.
* Upd.delete: ignore attempts to delete the last line, also occurs during shutdown.
*Release 20200621*:
New "disabled" mode, triggered by default if not backend.isatty().
*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.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs.upd",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python2, python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/a4/53/15cfc9c87d68107b08f00b018e01edc5f54a1fcf976574d12f23183fea9e/cs.upd-20240412.tar.gz",
"platform": null,
"description": "Single and multiple line status updates with minimal update sequences.\n\n*Latest release 20240412*:\n* Upd.run_task: provide the label as the new UpdProxy prefix.\n* Upd.insert: the supplied txt is the proxy.text, not the prefix.\n* UpdProxy.text: setting to None sets to self._text_auto() if present or makes no change.\n* New @without decorator to withdraw the Upd during a function.\n* print: use the builtin print directly if the Upd is disabled.\n\nThis is available as an output mode in `cs.logutils`.\n\nSingle line example:\n\n from cs.upd import Upd, nl, print\n .....\n with Upd() as U:\n for filename in filenames:\n U.out(filename)\n ... process filename ...\n U.nl('an informational line to stderr')\n print('a line to stdout')\n\nMultiline multithread example:\n\n from threading import Thread\n from cs.upd import Upd, print\n .....\n def runner(filename, proxy):\n # initial status message\n proxy.text = \"process %r\" % filename\n ... at various points:\n # update the status message with current progress\n proxy.text = '%r: progress status here' % filename\n # completed, remove the status message\n proxy.close()\n # print completion message to stdout\n print(\"completed\", filename)\n .....\n with Upd() as U:\n U.out(\"process files: %r\", filenames)\n Ts = []\n for filename in filenames:\n proxy = U.insert(1) # allocate an additional status line\n T = Thread(\n \"process \"+filename,\n target=runner,\n args=(filename, proxy))\n Ts.append(T)\n T.start()\n for T in Ts:\n T.join()\n\n## A note about Upd and terminals\n\nI routinely use an `Upd()` as a progress reporting tool for commands\nrunning on a terminal. This attaches to `sys.stderr` by default.\nHowever, it is usually not desirable to run an `Upd` display\nif the backend is not a tty/terminal.\nTherefore, an `Upd` has a \"disabled\" mode\nwhich performs no output;\nthe default behaviour is that this mode activates\nif the backend is not a tty (as tested by `backend.isatty()`).\nThe constructor has an optional parameter `disabled` to override\nthis default behaviour.\n\n## Function `demo()`\n\nA tiny demo function for visual checking of the basic functionality.\n\n## Function `nl(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1113604c0>, **kw)`\n\nWrite `msg` to `file` (default `sys.stdout`),\nwithout interfering with the `Upd` instance.\nThis is a thin shim for `Upd.print`.\n\n## Function `out(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x11135ba30>, **kw)`\n\nUpdate the status line of the default `Upd` instance.\nParameters are as for `Upd.out()`.\n\n## Function `pfxprint(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x11135bf40>, **kw)`\n\nWrapper for `cs.pfx.pfxprint` to pass `print_func=cs.upd.print`.\n\nProgrammes integrating `cs.upd` with use of the `cs.pfx.pfxprint`\nfunction should use this at import time:\n\n from cs.upd import pfxprint\n\n## Function `run_task(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1113601f0>, **kw)`\n\nTop level `run_task` function to call `Upd.run_task`.\n\n## Class `Upd(cs.obj.SingletonMixin, cs.resources.MultiOpenMixin, cs.threads.HasThreadState)`\n\nA `SingletonMixin` subclass for maintaining multiple status lines.\n\nThe default backend is `sys.stderr`.\n\n*Method `Upd.__init__(self, backend=None, columns=None, disabled=None)`*:\nInitialise the `Upd`.\n\nParameters:\n* `backend`: the output file, default from the environment\n variable `$CS_UPD_BACKEND` otherwise `sys.stderr`\n* `columns`: the width of the output,\n default from the width of the `backend` tty if it is a tty,\n `80` otherwise\n* `disabled`: if true, disable the output - just keep state;\n default true if the output is not a tty;\n this automatically silences the `Upd` if stderr is not a tty\n\n*Method `Upd.__enter_exit__(self)`*:\nGenerator supporting `__enter__` and `__exit__`.\n\nOn shutdown, if we are exiting because of an exception\nwhich is not a `SystemExit` with a `code` of `None` or `0`\nthen we preserve the status lines one screen.\nOtherwise we clean up the status lines.\n\n*Method `Upd.__getitem__(self, index)`*:\nThe text of the status line at `index`.\n\n*Method `Upd.__len__(self)`*:\nThe length of an `Upd` is the number of slots.\n\n*Method `Upd.above(self, need_newline=False)`*:\nContext manager to move to the top line of the `Upd` display,\nclear it, `yield`, redraw below.\n\nThis context manager is for use when interleaving _another_\nstream with the `Upd` display;\nif you just want to write lines above the display\nfor the same backend use `Upd.nl`.\n\nThe usual situation for `Upd.above`\nis interleaving `sys.stdout` and `sys.stderr`,\nwhich are often attached to the same terminal.\n\nNote that the caller's output should be flushed\nbefore exiting the suite\nso that the output is completed before the `Upd` resumes.\n\nExample:\n\n U = Upd() # default sys.stderr Upd\n ......\n with U.above():\n print('some message for stdout ...', flush=True)\n\n*Method `Upd.cursor_invisible(self)`*:\nMake the cursor vinisible.\n\n*Method `Upd.cursor_visible(self)`*:\nMake the cursor visible.\n\n*Method `Upd.delete(self, index)`*:\nDelete the status line at `index`.\n\nReturn the `UpdProxy` of the deleted status line.\n\n*Method `Upd.diff(oldtxt, newtxt, columns, raw_text=False)`*:\nCompute the text sequences required to update `oldtxt` to `newtxt`\npresuming the cursor is at the right hand end of `oldtxt`.\nThe available area is specified by `columns`.\n\nWe normalise `newtxt` as using `self.normalise`.\n`oldtxt` is presumed to be already normalised.\n\nIf `raw_text` is true (default `False`) we do not normalise `newtxt`\nbefore comparison.\n\n*Method `Upd.disable(self)`*:\nDisable updates.\n\n*Property `Upd.disabled`*:\nWhether this `Upd` is currently disabled.\n\n*Method `Upd.enable(self)`*:\nEnable updates.\n\n*Method `Upd.flush(self)`*:\nFlush the backend stream.\n\n*Method `Upd.insert(self, index, txt='', proxy=None, **proxy_kw) -> 'UpdProxy'`*:\nInsert a new status line at `index`.\nReturn the `UpdProxy` for the new status line.\n\n*Method `Upd.nl(self, txt, *a, redraw=False)`*:\nWrite `txt` to the backend followed by a newline.\n\nParameters:\n* `txt`: the message to write.\n* `a`: optional positional parameters;\n if not empty, `txt` is percent formatted against this list.\n* `redraw`: if true (default `False`) use the \"redraw\" method.\n\nThis uses one of two methods:\n* insert above:\n insert a line above the top status line and write the message there.\n* redraw:\n clear the top slot, write txt and a newline,\n redraw all the slots below.\n\nThe latter method is used if `redraw` is true\nor if `txt` is wider than `self.columns`\nor if there is no \"insert line\" capability.\n\n*Method `Upd.normalise(txt)`*:\nNormalise `txt` for display,\ncurrently implemented as:\n`unctrl(txt.rstrip())`.\n\n*Method `Upd.out(self, txt, *a, slot=0, raw_text=False, redraw=False) -> str`*:\nUpdate the status line at `slot` to `txt`.\nReturn the previous status line content.\n\nParameters:\n* `txt`: the status line text.\n* `a`: optional positional parameters;\n if not empty, `txt` is percent formatted against this list.\n* `slot`: which slot to update; default is `0`, the bottom slot\n* `raw_text`: if true (default `False`), do not normalise the text\n* `redraw`: if true (default `False`), redraw the whole line\n instead of doing the minimal and less visually annoying\n incremental change\n\n*`Upd.perthread_state`*\n\n*Method `Upd.proxy(self, index)`*:\nReturn the `UpdProxy` for `index`.\nReturns `None` if `index` is out of range.\nThe index `0` is never out of range;\nit will be autocreated if there are no slots yet.\n\n*Method `Upd.run_task(self, label: str, *, report_print=False, tick_delay: int = 0.3, tick_chars='|/-\\\\')`*:\nContext manager to display an `UpdProxy` for the duration of some task.\nIt yields the proxy.\n\n*Method `Upd.selfcheck(self)`*:\nSanity check the internal data structures.\n\nWarning: this uses asserts.\n\n*Method `Upd.shutdown(self, preserve_display=False)`*:\nClean out this `Upd`, optionally preserving the displayed status lines.\n\n*Method `Upd.ti_str(self, ti_name)`*:\nFetch the terminfo capability string named `ti_name`.\nReturn the string or `None` if not available.\n\n*Method `Upd.without(self, temp_state='', slot=0)`*:\nContext manager to clear the status line around a suite.\nReturns the status line text as it was outside the suite.\n\nThe `temp_state` parameter may be used to set the inner status line\ncontent if a value other than `''` is desired.\n\n## Class `UpdProxy`\n\nA proxy for a status line of a multiline `Upd`.\n\nThis provides a stable reference to a status line after it has been\ninstantiated by `Upd.insert`.\n\nThe status line can be accessed and set via the `.text` property.\n\nAn `UpdProxy` is also a context manager which self deletes on exit:\n\n U = Upd()\n ....\n with U.insert(1, 'hello!') as proxy:\n .... set proxy.text as needed ...\n # proxy now removed\n\n*Method `UpdProxy.__init__(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x111360790>, **kw)`*:\nInitialise a new `UpdProxy` status line.\n\nParameters:\n* `index`: optional position for the new proxy as for `Upd.insert`,\n default `1` (directly above the bottom status line)\n* `upd`: the `Upd` instance with which to associate this proxy,\n default the default `Upd` instance (associated with `sys.stderr`)\n* `text`: optional initial text for the new status line\n\n*Method `UpdProxy.__call__(self, msg, *a)`*:\nCalling the proxy sets its `.text` property\nin the form used by other messages: `(msg,*a)`\n\n*Method `UpdProxy.__del__(self)`*:\nDelete this proxy from its parent `Upd`.\n\n*Method `UpdProxy.delete(self)`*:\nDelete this proxy from its parent `Upd`.\n\n*Method `UpdProxy.extend_prefix(self, more_prefix, print_elapsed=False)`*:\nContext manager to append text to the prefix.\n\n*Method `UpdProxy.insert(self, index, txt='')`*:\nInsert a new `UpdProxy` at a position relative to this `UpdProxy`.\nReturn the new proxy.\n\nThis supports the positioning of related status lines.\n\n*Property `UpdProxy.prefix`*:\nThe current prefix string.\n\n*Method `UpdProxy.reset(self)`*:\nClear the proxy: set both the prefix and text to `''`.\n\n*Property `UpdProxy.suffix`*:\nThe current suffix string.\n\n*Property `UpdProxy.text`*:\nThe text of this proxy's slot, without the prefix.\n\n*Property `UpdProxy.width`*:\nThe available space for text after `self.prefix` and before `self.suffix`.\n\nThis is available width for uncropped text,\nintended to support presizing messages such as progress bars.\nSetting the text to something longer will crop the rightmost\nportion of the text which fits.\n\n## Function `uses_upd(*da, **dkw)`\n\nDecorator for functions accepting an optional `upd:Upd` parameter,\ndefault from `Upd.default() or Upd()`.\nThis also makes the `upd` the default `Upd` instance for this thread.\n\n## Function `with_upd_proxy(*da, **dkw)`\n\nDecorator to run `func` with an additional parameter `upd_proxy`\nbeing an `UpdProxy` for progress reporting.\n\nExample:\n\n @with_upd_proxy\n def func(*a, upd_proxy:UpdProxy, **kw):\n ... perform task, updating upd_proxy ...\n\n## Function `without(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1113613f0>, **kw)`\n\nContext manager withdraw the `Upd` while something runs.\n\nExample:\n\n from cs.upd import without\n ...\n with without():\n os.system('ls -la')\n\n# Release Log\n\n\n\n*Release 20240412*:\n* Upd.run_task: provide the label as the new UpdProxy prefix.\n* Upd.insert: the supplied txt is the proxy.text, not the prefix.\n* UpdProxy.text: setting to None sets to self._text_auto() if present or makes no change.\n* New @without decorator to withdraw the Upd during a function.\n* print: use the builtin print directly if the Upd is disabled.\n\n*Release 20240316*:\nFixed release upload artifacts.\n\n*Release 20240216*:\nNew without() context manager to withdraw the Upd while something runs.\n\n*Release 20240201*:\n* Upd.run_task: the label is now the only positional parameter.\n* @uses_upd: use @decorator to extract the inner function docstring etc.\n\n*Release 20231129*:\nSmall changes.\n\n*Release 20230401*:\n* Upd.run_task: use a local RunState to control the ticker, drop `runstate` parameter.\n* Renamed default HasThreadState.THREAD_STATE_ATTR to 'perthread_state'.\n* Keep a module level name for the default Upd instance.\n* Upd.shutdown: cope with shutdown early enough that there's no self._lock.\n* Honour new $CS_UPD_BACKEND envvar to support eg defaulting Upd to /dev/null.\n\n*Release 20230217*:\n* @uses_upd: provide Upd() if there is no current default.\n* @uses_upd: set the default Upd to the chosen Upd instance.\n* Upd: subclass MultiOpenMixin, drop close() and closed() methods; always make a default Upd instance in open state.\n* Upd: always define an initial slot and its UpdProxy, avoids a billion special cases elsewhere.\n* UpdProxy: accept index=None as \"make a bare UpdProxy for upd\" used in the Upd._reset setup code, reserving the magic self inserting mode for when index is not None.\n\n*Release 20230212*:\n* BREAKING: replace @upd_proxy (which fiddled upd.state) with @with_upd_proxy which supplies an upd_proxy parameter.\n* UpdProxy.text: bugfix spelling of _text_auto.\n* Upd now subclasses HasThreadState, replace global \"state\" with \"Upd.state\", related adjustments.\n* UpdProxy: new optional update_period parameter to limit the update frequency based on the time since last update.\n* Upd.insert: support keyword parameters for the created UpdProxy.\n\n*Release 20221228*:\nBugfix print: plumb the end= parameter.\n\n*Release 20220918*:\n* DROPPING PYTHON 2 SUPPORT.\n* New @uses_upd decorator for things accepting an optional upd=Upd().\n* UpdProxy.__init__: use @uses_upd, make text the only optional positional parameter.\n* New top level `run_task` context manager wrapping `Upd.run_task`.\n* Make all the top level functions accept an optional upd=Upd() parameter.\n* Upd.run_task: wrap the yield in a try/finally to manage the RunState.\n* Upd.run_task: set default tick_delay=0.3, 0.15 was too fast.\n* UpdProxy: new optional text_auto() callable parameter, used to compute proxy.text if proxy._text is empty.\n* UpdProxy.width: account for the suffix.\n\n*Release 20220619*:\nUpd.cursor_visible,cursor_invisible: actually send the escape sequence.\n\n*Release 20220606*:\nUpd.insert: insert(1) on empty slots autocreates slot 0.\n\n*Release 20220605*:\n* New Upd.run_task to add a status line for the duration of some task.\n* UpdProxy.extend_prefix: new optional print_elapsed parameter.\n\n*Release 20220530*:\n* UpdProxy: new .suffix property.\n* Upd: new run_task context manager to display an UpdProxy while something runs, with optional ticker.\n* Small bugfix.\n\n*Release 20220504*:\n* Upd.above: do a disable/enable around the yield, use try/finally for reliability.\n* Upd.delete: just warn about index out of range, seems it can happen during interpreter shutdown; to be debugged later.\n\n*Release 20220429*:\n* UpdProxy: accept optional prefix= parameter.\n* New pfxprint wrapper for cs.pfx.pfxprint, like the print wrapper.\n\n*Release 20210717*:\nDocstring update.\n\n*Release 20210507*:\nUpgrade dependency on cs.context for StackableState.\n\n*Release 20210428.4*:\nAnother dummy release during debugging.\n\n*Release 20210428.3*:\nRepeat the previous release, again again.\n\n*Release 20210428.2*:\nRepeat the previous release, again.\n\n*Release 20210428.1*:\nRepeat the previous release.\n\n*Release 20210428*:\nDo curses.setupterm() during iinit, avoid failure when stdout is not a tty.\n\n*Release 20210316*:\n* New UpdProxy.extend_prefix context manager to extend the proxy prefix around a suite.\n* New global \"state\" StackableStatei object with an automatic .upd attribute.\n* New @upd_proxy decorator to create an UpdProxy for the duration of a function call and record it as state.proxy.\n* Bugfix Upd.insert: add slots.insert and proxies.insert missing from the no-display path.\n* Rename private method Upd._adjust_text_v to public method Upd.diff.\n\n*Release 20210122*:\n* Autocreate slot 0 on first use.\n* Reliable cleanup at exit.\n* Fix a display small display issue.\n\n*Release 20201202*:\n* Fix for batch mode - handle failure of curses.setupterm(), throws TypeError.\n* Upd.insert: defer check for cuu1 capability until there's at least one line already.\n\n*Release 20201102*:\n* Upd.nl: simple approach when there are no status lines.\n* Upd: new cursor_visible and cursor_invisible methods to show and hide the cursor.\n\n*Release 20201026.1*:\nBugfix Upd.nl: simple output if there are no status lines to accomodate.\n\n*Release 20201026*:\nBugfix Upd.insert: accept insert(1) when len(self)==0.\n\n*Release 20201025*:\n* Upd: new .disabled property to allow inspection of disabledness.\n* Upd.insert: accept negative insert indices to position from the top of the list.\n* Upd.nl: use clear-to-end-of-line at the end of the message if available.\n* UpdProxy: turn .prefix into a property which causes a redraw when changed.\n* Upd.proxy(index): return None if the index is out of range, accomodates racy or incorrect behaviour by a user.\n* UpdProxy: cropped overflowing text gets a leading '<' to make it apparent.\n* UpdProxy: new .insert() method to support insterting new proxies with respect to an existing proxy.\n* UpdProxy: new reset() method, clears prefix and text.\n* UpdProxy.__init__: BREAKING: make all arguments optional to aid use.\n* Upd: do not make any slots unless required.\n* Make the compute-redraw-strings methods private.\n\n*Release 20200914*:\nBugfix UpdProxy.__enter__: return self.\n\n*Release 20200716.1*:\nDISTINFO: make the cs.obj requirement more specific due to the SingletonMixin API change.\n\n*Release 20200716*:\nUpdate for changed cs.obj.SingletonMixin API.\n\n*Release 20200626.1*:\nUpd.__exit__: bugfix test of SystemExit exceptions.\n\n*Release 20200626*:\n* UpdProxy: call self.delete on __del__.\n* If self._backend is None act as if disabled, occurs during shutdown.\n* Upd.delete: ignore attempts to delete the last line, also occurs during shutdown.\n\n*Release 20200621*:\nNew \"disabled\" mode, triggered by default if not backend.isatty().\n\n*Release 20200613*:\n* New UpdProxy.__call__ which sets the .text property in the manner of logging calls, with (msg,*a).\n* New Upd.normalise static method exposing the text normalisation `unctrl(text.rstrip())`.\n* New UpdProxy.prefix attribute with a fixed prefix for status updates; `prefix+text` is left cropped for display purposes when updated.\n* New UpdProxy.width property computing the space available after the prefix, useful for sizing things like progress bars.\n* Make UpdProxy a context manager which self deletes on exit.\n* Upd: make default backend=sys.stderr, eases the common case.\n* 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).\n* New out() top level function for convenience use with the default Upd().\n* New nl() top level function for writing a line to stderr.\n* 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.\n\n*Release 20200517*:\n* Multiline support!\n* Multiline support!\n* Multiline support!\n* New UpdProxy class to track a status line of a multiline Upd in the face of further inserts and deletes.\n* Upd(...) now returns a context manager to clean up the display on its exit.\n* Upd(...) is now a SingletonMixin in order to use the same state if set up in multiple places.\n\n*Release 20200229*:\n* Upd: can now be used as a context manager, clearing the line on exit.\n* Upd.without is now a context manager, returning the older state, and accepting an optional inner state (default \"\").\n* Upd is now a singleton factory, obsoleting upd_for.\n* Upd.nl: use \"insert line above\" mode if supported.\n\n*Release 20181108*:\nDocumentation improvements.\n\n*Release 20170903*:\n* New function upd_for(stream) returning singleton Upds.\n* Drop noStrip keyword argument/mode - always strip trailing whitespace.\n\n*Release 20160828*:\n* Use \"install_requires\" instead of \"requires\" in DISTINFO.\n* Add Upd.flush method.\n* Upd.out: fix longstanding trailing text erasure bug.\n* Upd.nl,out: accept optional positional parameters, use with %-formatting if supplied, just like logging.\n\n*Release 20150118*:\nmetadata fix\n\n*Release 20150116*:\nInitial PyPI release.\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Single and multiple line status updates with minimal update sequences.",
"version": "20240412",
"project_urls": {
"URL": "https://bitbucket.org/cameron_simpson/css/commits/all"
},
"split_keywords": [
"python2",
" python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "72380f560f71dcbafd0de1d6b8745ceb75e2939401c881c5f3dd14347ca9e1c4",
"md5": "578c8d3dcb509dbbbf408799fe4b4a1a",
"sha256": "a732f48f2ea5cadc1b21690fc03295707d122e5dbe875fa02f4a282cfbf0888b"
},
"downloads": -1,
"filename": "cs.upd-20240412-py3-none-any.whl",
"has_sig": false,
"md5_digest": "578c8d3dcb509dbbbf408799fe4b4a1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19442,
"upload_time": "2024-04-12T05:01:27",
"upload_time_iso_8601": "2024-04-12T05:01:27.295304Z",
"url": "https://files.pythonhosted.org/packages/72/38/0f560f71dcbafd0de1d6b8745ceb75e2939401c881c5f3dd14347ca9e1c4/cs.upd-20240412-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a45315cfc9c87d68107b08f00b018e01edc5f54a1fcf976574d12f23183fea9e",
"md5": "aab02b03ea79ff18d0190aa80116c608",
"sha256": "200c9f3cd2e8819077480d38a3d2f15d03b76c4449cf9b58a38cfc905cc3d41b"
},
"downloads": -1,
"filename": "cs.upd-20240412.tar.gz",
"has_sig": false,
"md5_digest": "aab02b03ea79ff18d0190aa80116c608",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24706,
"upload_time": "2024-04-12T05:01:29",
"upload_time_iso_8601": "2024-04-12T05:01:29.271220Z",
"url": "https://files.pythonhosted.org/packages/a4/53/15cfc9c87d68107b08f00b018e01edc5f54a1fcf976574d12f23183fea9e/cs.upd-20240412.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 05:01:29",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "cameron_simpson",
"bitbucket_project": "css",
"lcname": "cs.upd"
}
JSON