Metadata-Version: 2.1
Name: cs.delta
Version: 20240622
Summary: Utility functions around state changes.
Author-email: Cameron Simpson <cs@cskk.id.au>
License: GNU General Public License v3 or later (GPLv3+)
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/all
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/delta.py
Keywords: python2,python3
Platform: UNKNOWN
Classifier: Programming Language :: Python
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

Utility functions around state changes.

*Latest release 20240622*:
Changes to accomodate dropping BaseCommandOptions.runstate.

## Function `delta(old, new, keys=None)`

Return a mapping representing differences between the mappings
`old` and `new` for the specified `keys`.
If `keys` is not specified, the union of the keys of `old`
and `new` is used.

The returned mapping has a key for each changed value.
If the key does not exist in `new` the value is the `MISSING`
sentinel object otherwise it is `new[key]`.
Values are compared using `==`; if that raises `TypeError`
the values are considered not equal.

Example:

  >>> d1 = {1: 2, 3: 4, 5: 6}
  >>> d2 = {1: 2, 3: 44, 7: 8}
  >>> diff = delta(d1, d2)
  >>> diff  # doctest: +ELLIPSIS
  {3: 44, 5: <object object at ...>, 7: 8}
  >>> diff[5] is MISSING
  True

## Function `monitor(get_state, keys=None, *, ifunchanged=False, interval=0.3, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x1072e81f0>)`

A generator yielding 3-tuples of `(old,new,delta(old,new,keys))`
at poll intervals of `interval` seconds.

Parameters:
* `get_state`: a callable which polls the current state,
  returning a mapping
* `keys`: an optional iterable of keys of interest;
  if omitted, all the old and new mapping keys are examined
* `ifunchanged`: optional flag, default `False`;
  if true yield a tuple on every poll instead of only when a
  state change is seen
* `interval`: an optional interpoll `time.sleep` period,
  default `0.3`s
* `runstate`: an optional `RunState`, whose `cancelled`
  attribute will be polled for loop termination

# Release Log



*Release 20240622*:
Changes to accomodate dropping BaseCommandOptions.runstate.

*Release 20240316*:
Fixed release upload artifacts.

*Release 20240214*:
Initial PyPI release.

