cs-psutils 20250108__py2.py3-none-any.whl

cs/psutils.py

@@ -0,0 +1,521 @@
+#!/usr/bin/python
+#
+
+r'''
+Assorted process and subprocess management functions.
+
+Not to be confused with the excellent
+(psutil)[https://pypi.org/project/psutil/] package.
+'''
+
+import builtins
+from contextlib import contextmanager
+import errno
+import io
+from itertools import chain
+import logging
+import os
+import shlex
+from signal import SIGTERM, SIGKILL, signal
+from subprocess import DEVNULL as subprocess_DEVNULL, PIPE, Popen, run as subprocess_run
+import sys
+import time
+
+from cs.deco import fmtdoc, uses_cmd_options
+from cs.gimmicks import trace, warning, DEVNULL
+from cs.pfx import pfx_call
+
+__version__ = '20250108'
+
+DISTINFO = {
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+    ],
+    'install_requires': [
+        'cs.deco',
+        'cs.gimmicks>=devnull',
+        'cs.pfx',
+    ],
+}
+
+# maximum number of bytes usable in the argv list for the exec*() functions
+# 262144 below is from MacOS El Capitan "sysctl kern.argmax", then
+# halved because even allowing for the size of the environment this
+# can be too big. Unsure why.
+MAX_ARGV = 262144 // 2
+
+def stop(pid, signum=SIGTERM, wait=None, do_SIGKILL=False):
+  ''' Stop the process specified by `pid`, optionally await its demise.
+
+      Parameters:
+      * `pid`: process id.
+        If `pid` is a string, treat as a process id file and read the
+        process id from it.
+      * `signum`: the signal to send, default `signal.SIGTERM`.
+      * `wait`: whether to wait for the process, default `None`.
+        If `None`, return `True` (signal delivered).
+        If `0`, wait indefinitely until the process exits as tested by
+        `os.kill(pid, 0)`.
+        If greater than 0, wait up to `wait` seconds for the process to die;
+        if it exits, return `True`, otherwise `False`;
+      * `do_SIGKILL`: if true (default `False`),
+        send the process `signal.SIGKILL` as a final measure before return.
+  '''
+  if isinstance(pid, str):
+    return stop(int(open(pid, encoding='ascii').read().strip()))
+  os.kill(pid, signum)
+  if wait is None:
+    return True
+  assert wait >= 0, "wait (%s) should be >= 0" % (wait,)
+  now = time.time()
+  then = now + wait
+  while True:
+    time.sleep(0.1)
+    if wait == 0 or time.time() < then:
+      try:
+        os.kill(pid, 0)
+      except OSError as e:
+        if e.errno != errno.ESRCH:
+          raise
+        # process no longer present
+        return True
+    else:
+      if do_SIGKILL:
+        try:
+          os.kill(pid, SIGKILL)
+        except OSError as e:
+          if e.errno != errno.ESRCH:
+            raise
+      return False
+
+@contextmanager
+def signal_handler(sig, handler, call_previous=False):
+  ''' Context manager to push a new signal handler,
+      yielding the old handler,
+      restoring the old handler on exit.
+      If `call_previous` is true (default `False`)
+      also call the old handler after the new handler on receipt of the signal.
+
+      Parameters:
+      * `sig`: the `int` signal number to catch
+      * `handler`: the handler function to call with `(sig,frame)`
+      * `call_previous`: optional flag (default `False`);
+        if true, also call the old handler (if any) after `handler`
+  '''
+  if call_previous:
+    # replace handler() with a wrapper to call both it and the old handler
+    handler0 = handler
+
+    def handler(sig, frame):  # pylint:disable=function-redefined
+      ''' Call the handler and then the previous handler if requested.
+      '''
+      handler0(sig, frame)
+      if callable(old_handler):
+        old_handler(sig, frame)
+
+  old_handler = signal(sig, handler)
+  try:
+    yield old_handler
+  finally:
+    # restiore the previous handler
+    signal(sig, old_handler)
+
+@contextmanager
+def signal_handlers(sig_hnds, call_previous=False, _stacked=None):
+  ''' Context manager to stack multiple signal handlers,
+      yielding a mapping of `sig`=>`old_handler`.
+
+      Parameters:
+      * `sig_hnds`: a mapping of `sig`=>`new_handler`
+        or an iterable of `(sig,new_handler)` pairs
+      * `call_previous`: optional flag (default `False`), passed
+        to `signal_handler()`
+  '''
+  if _stacked is None:
+    _stacked = {}
+  try:
+    items = sig_hnds.items
+  except AttributeError:
+    # (sig,hnd),... from iterable
+    it = iter(sig_hnds)
+  else:
+    # (sig,hnd),... from mapping
+    it = iter(items())
+  try:
+    sig, handler = next(it)
+  except StopIteration:
+    pass
+  else:
+    with signal_handler(sig, handler,
+                        call_previous=call_previous) as old_handler:
+      _stacked[sig] = old_handler
+      with signal_handlers(it, call_previous=call_previous,
+                           _stacked=_stacked) as stacked:
+        yield stacked
+    return
+  yield _stacked
+
+def write_pidfile(path, pid=None):
+  ''' Write a process id to a pid file.
+
+      Parameters:
+      * `path`: the path to the pid file.
+      * `pid`: the process id to write, defautl from `os.getpid`.
+  '''
+  if pid is None:
+    pid = os.getpid()
+  with open(path, 'w', encoding='ascii') as pidfp:
+    print(pid, file=pidfp)
+
+def remove_pidfile(path):
+  ''' Truncate and remove a pidfile, permissions permitting.
+  '''
+  try:
+    with open(path, "wb"):  # pylint: disable=unspecified-encoding
+      pass
+    os.remove(path)
+  except OSError as e:
+    if e.errno != errno.EPERM:
+      raise
+
+@contextmanager
+def PidFileManager(path, pid=None):
+  ''' Context manager for a pid file.
+
+      Parameters:
+      * `path`: the path to the process id file.
+      * `pid`: the process id to store in the pid file,
+        default from `os.etpid`.
+
+      Writes the process id file at the start
+      and removes the process id file at the end.
+  '''
+  write_pidfile(path, pid=pid)
+  try:
+    yield
+  finally:
+    remove_pidfile(path)
+
+@uses_cmd_options(doit=True, quiet=False)
+def run(
+    argv,
+    *,
+    check=True,
+    doit: bool,
+    input=None,
+    logger=None,
+    print=None,
+    fold=None,
+    quiet: bool,
+    remote=None,
+    ssh_exe=None,
+    stdin=None,
+    **subp_options,
+):
+  ''' Run a command via `subprocess.run`.
+      Return the `CompletedProcess` result or `None` if `doit` is false.
+
+      Positional parameter:
+      * `argv`: the command line to run
+
+      Note that `argv` is passed through `prep_argv(argv,remote=remote,ssh_exe=ssh_exe)`
+      before use, allowing direct invocation with conditional parts.
+      See the `prep_argv` function for details.
+
+      Keyword parameters:
+      * `check`: passed to `subprocess.run`, default `True`;
+        NB: _unlike_ the `subprocess.run` default, which is `False`
+      * `doit`: optional flag, default `True`;
+        if false do not run the command and return `None`
+      * `fold`: optional flag, passed to `print_argv`
+      * `input`: default `None`: alternative to `stdin`;
+        passed to `subprocess.run`
+      * `logger`: optional logger, default `None`;
+        if `True`, use `logging.getLogger()`;
+        if not `None` or `False` trace using `print_argv`
+      * `quiet`: default `False`; if false, print the command and its output
+      * `remote`: optional remote target on which to run `argv`
+      * `ssh_exe`: optional command string for the remote shell
+      * `stdin`: standard input for the subprocess, default `subprocess.DEVNULL`;
+        passed to `subprocess.run`
+
+      Other keyword parameters are passed to `subprocess.run`.
+  '''
+  argv = prep_argv(*argv, remote=remote, ssh_exe=ssh_exe)
+  if logger is True:
+    logger = logging.getLogger()
+  if not doit:
+    if not quiet:
+      if logger:
+        trace("skip: %s", shlex.join(argv))
+      else:
+        if fold is None:
+          fold = True
+        print_argv(*argv, fold=fold, print=print)
+    return None
+  if not quiet:
+    if logger:
+      trace("+ %s", shlex.join(argv))
+    else:
+      if fold is None:
+        fold = False
+      print_argv(*argv, indent="+ ", file=sys.stderr, fold=fold, print=print)
+  if input is None:
+    if stdin is None:
+      stdin = subprocess_DEVNULL
+  elif stdin is not None:
+    raise ValueError("you may not specify both input and stdin")
+  cp = pfx_call(
+      subprocess_run,
+      argv,
+      check=check,
+      input=input,
+      stdin=stdin,
+      **subp_options,
+  )
+  if cp.stderr:
+    # TODO: is this a good thing? I have my doubts
+    print(" stderr:")
+    print(" ", cp.stderr.rstrip().replace("\n", "\n  "))
+  if cp.returncode != 0:
+    warning(
+        "run fails, exit code %s from %s",
+        cp.returncode,
+        shlex.join(cp.args),
+    )
+  return cp
+
+@uses_cmd_options(quiet=False, ssh_exe='ssh')
+def pipefrom(
+    argv,
+    *,
+    quiet: bool,
+    remote=None,
+    ssh_exe,
+    text=True,
+    stdin=DEVNULL,
+    **popen_kw
+):
+  ''' Pipe text (usually) from a command using `subprocess.Popen`.
+      Return the `Popen` object with `.stdout` as a pipe.
+
+      Parameters:
+      * `argv`: the command argument list
+      * `quiet`: optional flag, default `False`;
+        if true, print the command to `stderr`
+      * `text`: optional flag, default `True`; passed to `Popen`.
+      * `stdin`: optional value for `Popen`'s `stdin`, default `DEVNULL`
+      Other keyword arguments are passed to `Popen`.
+
+      Note that `argv` is passed through `prep_argv` before use,
+      allowing direct invocation with conditional parts.
+      See the `prep_argv` function for details.
+  '''
+  argv = prep_argv(*argv, remote=remote, ssh_exe=ssh_exe)
+  if not quiet:
+    print_argv(*argv, indent="+ ", end=" |\n", file=sys.stderr)
+  return Popen(argv, stdout=PIPE, text=text, stdin=stdin, **popen_kw)
+
+# TODO: text= parameter?
+@uses_cmd_options(quiet=False, ssh_exe='ssh')
+def pipeto(argv, *, quiet: bool, remote=None, ssh_exe, **kw):
+  ''' Pipe text to a command.
+      Optionally trace invocation.
+      Return the Popen object with .stdin encoded as text.
+
+      Parameters:
+      * `argv`: the command argument list
+      * `trace`: if true (default `False`),
+        if `trace` is `True`, recite invocation to stderr
+        otherwise presume that `trace` is a stream
+        to which to recite the invocation.
+
+      Other keyword arguments are passed to the `io.TextIOWrapper`
+      which wraps the command's input.
+
+      Note that `argv` is passed through `prep_argv` before use,
+      allowing direct invocation with conditional parts.
+      See the `prep_argv` function for details.
+  '''
+  argv = prep_argv(*argv)
+  if not quiet:
+    print_argv(*argv, indent="| ", file=sys.stderr)
+  P = Popen(argv, stdin=PIPE)  # pylint: disable=consider-using-with
+  P.stdin = io.TextIOWrapper(P.stdin, **kw)
+  return P
+
+@fmtdoc
+def groupargv(pre_argv, argv, post_argv=(), max_argv=None, encode=False):
+  ''' Distribute the array `argv` over multiple arrays
+      to fit within `MAX_ARGV`.
+      Return a list of argv lists.
+
+      Parameters:
+      * `pre_argv`: the sequence of leading arguments
+      * `argv`: the sequence of arguments to distribute; this may not be empty
+      * `post_argv`: optional, the sequence of trailing arguments
+      * `max_argv`: optional, the maximum length of each distributed
+        argument list, default from `MAX_ARGV`: `{MAX_ARGV}`
+      * `encode`: default `False`.
+        If true, encode the argv sequences into bytes for accurate tallying.
+        If `encode` is a Boolean,
+        encode the elements with their .encode() method.
+        If `encode` is a `str`, encode the elements with their `.encode()`
+        method with `encode` as the encoding name;
+        otherwise presume that `encode` is a callable
+        for encoding each element.
+
+      The returned argv arrays will contain the encoded element values.
+  '''
+  if not argv:
+    raise ValueError("argv may not be empty")
+  if max_argv is None:
+    max_argv = MAX_ARGV
+  if encode:
+    if isinstance(encode, bool):
+      pre_argv = [arg.encode() for arg in pre_argv]
+      argv = [arg.encode() for arg in argv]
+      post_argv = [arg.encode() for arg in post_argv]
+    elif isinstance(encode, str):
+      pre_argv = [arg.encode(encode) for arg in pre_argv]
+      argv = [arg.encode(encode) for arg in argv]
+      post_argv = [arg.encode(encode) for arg in post_argv]
+    else:
+      pre_argv = [encode(arg) for arg in pre_argv]
+      argv = [encode(arg) for arg in argv]
+      post_argv = [encode(arg) for arg in post_argv]
+  else:
+    pre_argv = list(pre_argv)
+    post_argv = list(post_argv)
+  pre_nbytes = sum(len(arg) + 1 for arg in pre_argv)
+  post_nbytes = sum(len(arg) + 1 for arg in post_argv)
+  argvs = []
+  available = max_argv - pre_nbytes - post_nbytes
+  per = []
+  for arg in argv:
+    nbytes = len(arg) + 1
+    if available - nbytes < 0:
+      if not per:
+        raise ValueError(
+            "cannot fit argument into argv: available=%d, len(arg)=%d: %r" %
+            (available, len(arg), arg)
+        )
+      argvs.append(pre_argv + per + post_argv)
+      available = max_argv - pre_nbytes - post_nbytes
+      per = []
+    per.append(arg)
+    available -= nbytes
+  if per:
+    argvs.append(pre_argv + per + post_argv)
+  return argvs
+
+@uses_cmd_options(ssh_exe='ssh')
+def prep_argv(*argv, ssh_exe, remote=None):
+  ''' A trite list comprehension to reduce an argument list `*argv`
+      to the entries which are not `None` or `False`
+      and to flatten other entries which are not strings.
+
+      This exists ease the construction of argument lists
+      with methods like this:
+
+          >>> command_exe = 'hashindex'
+          >>> hashname = 'sha1'
+          >>> quiet = False
+          >>> verbose = True
+          >>> prep_argv(
+          ...     command_exe,
+          ...     quiet and '-q',
+          ...     verbose and '-v',
+          ...     hashname and ('-h', hashname),
+          ... )
+          ['hashindex', '-v', '-h', 'sha1']
+
+      where `verbose` is a `bool` governing the `-v` option
+      and `hashname` is either `str` to be passed with `-h hashname`
+      or `None` to omit the option.
+
+      If `remote` is not `None` it is taken to be a remote host on
+      which to run `argv`. This is done via the `ssh_exe` argument,
+      which defaults to the string `'ssh'`. The value of `ssh_exe`
+      is a command string parsed with `shlex.split`. A new `argv`
+      is computed as:
+
+          [
+              *shlex.split(ssh_exe),
+              remote,
+              '--',
+              shlex.join(argv),
+          ]
+  '''
+  argv = list(
+      chain(
+          *[
+              ((arg,) if isinstance(arg, str) else arg)
+              for arg in argv
+              if arg is not None and arg is not False
+          ]
+      )
+  )
+  if remote is not None:
+    argv = [
+        *shlex.split(ssh_exe),
+        remote,
+        '--',
+        shlex.join(argv),
+    ]
+  return argv
+
+def print_argv(
+    *argv,
+    indent="",
+    subindent="  ",
+    end="\n",
+    file=None,
+    fold=False,
+    print=None,
+):
+  ''' Print an indented possibly folded command line.
+  '''
+  if file is None:
+    file = sys.stdout
+  if print is None:
+    print = builtins.print
+  pr_argv = []
+  was_opt = False
+  for i, arg in enumerate(argv):
+    if i == 0:
+      pr_argv.append(indent)
+      was_opt = False
+    elif len(arg) >= 2 and arg.startswith('-'):
+      if fold:
+        # options get a new line
+        pr_argv.append(" \\\n" + indent + subindent)
+      else:
+        pr_argv.append(" ")
+      was_opt = True
+    else:
+      if was_opt:
+        pr_argv.append(" ")
+      elif fold:
+        # nonoptions get a new line
+        pr_argv.append(" \\\n" + indent + subindent)
+      else:
+        pr_argv.append(" ")
+      was_opt = False
+    pr_argv.append(shlex.quote(arg))
+  print(*pr_argv, sep='', end=end, file=file)
+
+if __name__ == '__main__':
+  for test_max_argv in 64, 20, 16, 8:
+    print(
+        test_max_argv,
+        repr(
+            groupargv(
+                ['cp', '-a'], ['a', 'bbbb', 'ddddddddddddd'], ['end'],
+                max_argv=test_max_argv,
+                encode=True
+            )
+        )
+    )

cs_psutils-20250108.dist-info/METADATA

@@ -0,0 +1,315 @@
+Metadata-Version: 2.3
+Name: cs-psutils
+Version: 20250108
+Summary: Assorted process and subprocess management functions.
+Keywords: python2,python3
+Author-email: Cameron Simpson <cs@cskk.id.au>
+Description-Content-Type: text/markdown
+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+)
+Requires-Dist: cs.deco>=20250103
+Requires-Dist: cs.gimmicks>=20220429
+Requires-Dist: cs.pfx>=20241208
+Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
+Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
+Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
+Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/psutils.py
+
+Assorted process and subprocess management functions.
+
+*Latest release 20250108*:
+run: accept new optional fold= parameter, plumb to print_argv.
+
+Not to be confused with the excellent
+(psutil)[https://pypi.org/project/psutil/] package.
+
+## <a name="groupargv"></a>`groupargv(pre_argv, argv, post_argv=(), max_argv=None, encode=False)`
+
+Distribute the array `argv` over multiple arrays
+to fit within `MAX_ARGV`.
+Return a list of argv lists.
+
+Parameters:
+* `pre_argv`: the sequence of leading arguments
+* `argv`: the sequence of arguments to distribute; this may not be empty
+* `post_argv`: optional, the sequence of trailing arguments
+* `max_argv`: optional, the maximum length of each distributed
+  argument list, default from `MAX_ARGV`: `131072`
+* `encode`: default `False`.
+  If true, encode the argv sequences into bytes for accurate tallying.
+  If `encode` is a Boolean,
+  encode the elements with their .encode() method.
+  If `encode` is a `str`, encode the elements with their `.encode()`
+  method with `encode` as the encoding name;
+  otherwise presume that `encode` is a callable
+  for encoding each element.
+
+The returned argv arrays will contain the encoded element values.
+
+## <a name="PidFileManager"></a>`PidFileManager(path, pid=None)`
+
+Context manager for a pid file.
+
+Parameters:
+* `path`: the path to the process id file.
+* `pid`: the process id to store in the pid file,
+  default from `os.etpid`.
+
+Writes the process id file at the start
+and removes the process id file at the end.
+
+## <a name="pipefrom"></a>`pipefrom(argv, *, quiet: bool, remote=None, ssh_exe, text=True, stdin=-3, **popen_kw)`
+
+Pipe text (usually) from a command using `subprocess.Popen`.
+Return the `Popen` object with `.stdout` as a pipe.
+
+Parameters:
+* `argv`: the command argument list
+* `quiet`: optional flag, default `False`;
+  if true, print the command to `stderr`
+* `text`: optional flag, default `True`; passed to `Popen`.
+* `stdin`: optional value for `Popen`'s `stdin`, default `DEVNULL`
+Other keyword arguments are passed to `Popen`.
+
+Note that `argv` is passed through `prep_argv` before use,
+allowing direct invocation with conditional parts.
+See the `prep_argv` function for details.
+
+## <a name="pipeto"></a>`pipeto(argv, *, quiet: bool, remote=None, ssh_exe, **kw)`
+
+Pipe text to a command.
+Optionally trace invocation.
+Return the Popen object with .stdin encoded as text.
+
+Parameters:
+* `argv`: the command argument list
+* `trace`: if true (default `False`),
+  if `trace` is `True`, recite invocation to stderr
+  otherwise presume that `trace` is a stream
+  to which to recite the invocation.
+
+Other keyword arguments are passed to the `io.TextIOWrapper`
+which wraps the command's input.
+
+Note that `argv` is passed through `prep_argv` before use,
+allowing direct invocation with conditional parts.
+See the `prep_argv` function for details.
+
+## <a name="prep_argv"></a>`prep_argv(*argv, ssh_exe, remote=None)`
+
+A trite list comprehension to reduce an argument list `*argv`
+to the entries which are not `None` or `False`
+and to flatten other entries which are not strings.
+
+This exists ease the construction of argument lists
+with methods like this:
+
+    >>> command_exe = 'hashindex'
+    >>> hashname = 'sha1'
+    >>> quiet = False
+    >>> verbose = True
+    >>> prep_argv(
+    ...     command_exe,
+    ...     quiet and '-q',
+    ...     verbose and '-v',
+    ...     hashname and ('-h', hashname),
+    ... )
+    ['hashindex', '-v', '-h', 'sha1']
+
+where `verbose` is a `bool` governing the `-v` option
+and `hashname` is either `str` to be passed with `-h hashname`
+or `None` to omit the option.
+
+If `remote` is not `None` it is taken to be a remote host on
+which to run `argv`. This is done via the `ssh_exe` argument,
+which defaults to the string `'ssh'`. The value of `ssh_exe`
+is a command string parsed with `shlex.split`. A new `argv`
+is computed as:
+
+    [
+        *shlex.split(ssh_exe),
+        remote,
+        '--',
+        shlex.join(argv),
+    ]
+
+## <a name="print_argv"></a>`print_argv(*argv, indent='', subindent='  ', end='\n', file=None, fold=False, print=None)`
+
+Print an indented possibly folded command line.
+
+## <a name="remove_pidfile"></a>`remove_pidfile(path)`
+
+Truncate and remove a pidfile, permissions permitting.
+
+## <a name="run"></a>`run(argv, *, check=True, doit: bool, input=None, logger=None, print=None, fold=None, quiet: bool, remote=None, ssh_exe=None, stdin=None, **subp_options)`
+
+Run a command via `subprocess.run`.
+Return the `CompletedProcess` result or `None` if `doit` is false.
+
+Positional parameter:
+* `argv`: the command line to run
+
+Note that `argv` is passed through `prep_argv(argv,remote=remote,ssh_exe=ssh_exe)`
+before use, allowing direct invocation with conditional parts.
+See the `prep_argv` function for details.
+
+Keyword parameters:
+* `check`: passed to `subprocess.run`, default `True`;
+  NB: _unlike_ the `subprocess.run` default, which is `False`
+* `doit`: optional flag, default `True`;
+  if false do not run the command and return `None`
+* `fold`: optional flag, passed to `print_argv`
+* `input`: default `None`: alternative to `stdin`;
+  passed to `subprocess.run`
+* `logger`: optional logger, default `None`;
+  if `True`, use `logging.getLogger()`;
+  if not `None` or `False` trace using `print_argv`
+* `quiet`: default `False`; if false, print the command and its output
+* `remote`: optional remote target on which to run `argv`
+* `ssh_exe`: optional command string for the remote shell
+* `stdin`: standard input for the subprocess, default `subprocess.DEVNULL`;
+  passed to `subprocess.run`
+
+Other keyword parameters are passed to `subprocess.run`.
+
+## <a name="signal_handler"></a>`signal_handler(sig, handler, call_previous=False)`
+
+Context manager to push a new signal handler,
+yielding the old handler,
+restoring the old handler on exit.
+If `call_previous` is true (default `False`)
+also call the old handler after the new handler on receipt of the signal.
+
+Parameters:
+* `sig`: the `int` signal number to catch
+* `handler`: the handler function to call with `(sig,frame)`
+* `call_previous`: optional flag (default `False`);
+  if true, also call the old handler (if any) after `handler`
+
+## <a name="signal_handlers"></a>`signal_handlers(sig_hnds, call_previous=False, _stacked=None)`
+
+Context manager to stack multiple signal handlers,
+yielding a mapping of `sig`=>`old_handler`.
+
+Parameters:
+* `sig_hnds`: a mapping of `sig`=>`new_handler`
+  or an iterable of `(sig,new_handler)` pairs
+* `call_previous`: optional flag (default `False`), passed
+  to `signal_handler()`
+
+## <a name="stop"></a>`stop(pid, signum=<Signals.SIGTERM: 15>, wait=None, do_SIGKILL=False)`
+
+Stop the process specified by `pid`, optionally await its demise.
+
+Parameters:
+* `pid`: process id.
+  If `pid` is a string, treat as a process id file and read the
+  process id from it.
+* `signum`: the signal to send, default `signal.SIGTERM`.
+* `wait`: whether to wait for the process, default `None`.
+  If `None`, return `True` (signal delivered).
+  If `0`, wait indefinitely until the process exits as tested by
+  `os.kill(pid, 0)`.
+  If greater than 0, wait up to `wait` seconds for the process to die;
+  if it exits, return `True`, otherwise `False`;
+* `do_SIGKILL`: if true (default `False`),
+  send the process `signal.SIGKILL` as a final measure before return.
+
+## <a name="write_pidfile"></a>`write_pidfile(path, pid=None)`
+
+Write a process id to a pid file.
+
+Parameters:
+* `path`: the path to the pid file.
+* `pid`: the process id to write, defautl from `os.getpid`.
+
+# Release Log
+
+
+
+*Release 20250108*:
+run: accept new optional fold= parameter, plumb to print_argv.
+
+*Release 20241206*:
+run(): accept new remote= and ssh_exe= parameters to support remote execution, default via @uses_cmd_options(ssh_exe).
+
+*Release 20241122*:
+* print_argv: new print= parameter to provide a print() function, refactor to use print instead of file.write.
+* run: new optional print parameter, plumb to print_argv.
+* Use @uses_doit and @uses_quiet to provide the default quiet and doit states.
+
+*Release 20240316*:
+Fixed release upload artifacts.
+
+*Release 20240211*:
+* run: new optional input= parameter to presupply input data.
+* New prep_argv(*argv) function to flatten and trim computes argv lists; use automatically in run(), pipeot(), pipefrom().
+
+*Release 20231129*:
+run(): default stdin=subprocess.DEVNULL.
+
+*Release 20230612*:
+* pipefrom: default stdin=DEVNULL.
+* Make many parameters keyword only.
+
+*Release 20221228*:
+* signal_handlers: bugfix iteration of sig_hnds.
+* Use cs.gimmicks instead of cs.logutils.
+* Drop use of cs.upd, fixes circular import; users of run() may need to call "with Upd().above()" themselves.
+
+*Release 20221118*:
+run: do not print cp.stdout.
+
+*Release 20220805*:
+run: print trace to stderr.
+
+*Release 20220626*:
+run: default quiet=True.
+
+*Release 20220606*:
+* run: fold in the superior run() from cs.ebooks.
+* pipefrom,pipeto: replace trace= with quiet= like run().
+* print_argv: add an `end` parameter (used by pipefrom).
+
+*Release 20220531*:
+* New print_argv function for writing shell command lines out nicely.
+* Bump requirements for cs.gimmicks.
+
+*Release 20220504*:
+signal_handlers: reshape try/except to avoid confusing traceback.
+
+*Release 20220429*:
+* New signal_handler(sig,handler,call_previous=False) context manager to push a signal handler.
+* New signal_handlers() context manager to stack handlers for multiple signals.
+
+*Release 20190101*:
+Bugfix context manager cleanup. groupargv improvements.
+
+*Release 20171112*:
+Bugfix array length counting.
+
+*Release 20171110*:
+New function groupargv for breaking up argv lists to fit within the maximum argument limit; constant MAX_ARGV for the default limit.
+
+*Release 20171031*:
+run: accept optional pids parameter, a setlike collection of process ids.
+
+*Release 20171018*:
+run: replace `trace` parameter with `logger`, default None
+
+*Release 20170908.1*:
+remove dependency on cs.pfx
+
+*Release 20170908*:
+run: pass extra keyword arguments to subprocess.call
+
+*Release 20170906.1*:
+Add run, pipefrom and pipeto - were incorrectly in another module.
+
+*Release 20170906*:
+First PyPI release.

cs_psutils-20250108.dist-info/RECORD

@@ -0,0 +1,4 @@
+cs/psutils.py,sha256=-RyWcFNHM1MxARVWWccNAsSWzab-jb9Hf-MmgB60sXc,15911
+cs_psutils-20250108.dist-info/WHEEL,sha256=ssQ84EZ5gH1pCOujd3iW7HClo_O_aDaClUbX4B8bjKY,100
+cs_psutils-20250108.dist-info/METADATA,sha256=_AqLS6YaY_6MpKUCSWz5_mhSwKsI8GWli_t6kEgUcjQ,11184
+cs_psutils-20250108.dist-info/RECORD,,

cs_psutils-20250108.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.10.1
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any