Package: cs.psutils
Assorted process and subprocess management functions.Latest 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().Not to be confused with the excellent
(psutil)[https://pypi.org/project/psutil/] package.Functiongroupargv(pre_argv, argv, post_argv=(), max_argv=None, encode=False)Distribute the arrayargvover multiple arrays
to fit withinMAX_ARGV.
Return a list of argv lists.Parameters:pre_argv: the sequence of leading argumentsargv: the sequence of arguments to distribute; this may not be emptypost_argv: optional, the sequence of trailing argumentsmax_argv: optional, the maximum length of each distributed
argument list, default fromMAX_ARGV:131072encode: defaultFalse.
If true, encode the argv sequences into bytes for accurate tallying.
Ifencodeis a Boolean,
encode the elements with their .encode() method.
Ifencodeis astr, encode the elements with their.encode()method withencodeas the encoding name;
otherwise presume thatencodeis a callable
for encoding each element.The returned argv arrays will contain the encoded element values.FunctionPidFileManager(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 fromos.etpid.Writes the process id file at the start
and removes the process id file at the end.Functionpipefrom(argv, *, quiet=False, text=True, stdin=-3, **popen_kw)Pipe text (usually) from a command usingsubprocess.Popen.
Return thePopenobject with.stdoutas a pipe.Parameters:argv: the command argument listquiet: optional flag, defaultFalse;
if true, print the command tostderrtext: optional flag, defaultTrue; passed toPopen.stdin: optional value forPopen'sstdin, defaultDEVNULLOther keyword arguments are passed toPopen.Note thatargvis passed throughprep_argvbefore use,
allowing direct invocation with conditional parts.
See theprep_argvfunction for details.Functionpipeto(argv, *, quiet=False, **kw)Pipe text to a command.
Optionally trace invocation.
Return the Popen object with .stdin encoded as text.Parameters:argv: the command argument listtrace: if true (defaultFalse),
iftraceisTrue, recite invocation to stderr
otherwise presume thattraceis a stream
to which to recite the invocation.Other keyword arguments are passed to theio.TextIOWrapperwhich wraps the command's input.Note thatargvis passed throughprep_argvbefore use,
allowing direct invocation with conditional parts.
See theprep_argvfunction for details.Functionprep_argv(*argv)A trite list comprehension to reduce an argument list*argvto the entries which are notNoneorFalseand 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']whereverboseis aboolgoverning the-voption
andhashnameis eitherstrto be passed with-h hashnameorNoneto omit the option.Functionprint_argv(*argv, indent='', subindent='  ', end='\n', file=None, fold=False)Print an indented possibly folded command line.Functionremove_pidfile(path)Truncate and remove a pidfile, permissions permitting.Functionrun(argv, *, doit=True, logger=None, quiet=True, input=None, stdin=None, **subp_options)Run a command viasubprocess.run.
Return theCompletedProcessresult orNoneifdoitis false.Parameters:argv: the command line to rundoit: optional flag, defaultTrue;
if false do not run the command and returnNonelogger: optional logger, defaultNone;
ifTrue, uselogging.getLogger();
if notNoneorFalsetrace usingprint_argvquiet: defaultTrue; if false, print the command and its outputinput: defaultNone: alternative tostdin;
passed tosubprocess.runstdin: standard input for the subprocess, defaultsubprocess.DEVNULL;
passed tosubprocess.runsubp_options: optional mapping of keyword arguments
to pass tosubprocess.runNote thatargvis passed throughprep_argvbefore use,
allowing direct invocation with conditional parts.
See theprep_argvfunction for details.Functionsignal_handler(sig, handler, call_previous=False)Context manager to push a new signal handler,
yielding the old handler,
restoring the old handler on exit.
Ifcall_previousis true (defaultFalse)
also call the old handler after the new handler on receipt of the signal.Parameters:sig: theintsignal number to catchhandler: the handler function to call with(sig,frame)call_previous: optional flag (defaultFalse);
if true, also call the old handler (if any) afterhandlerFunctionsignal_handlers(sig_hnds, call_previous=False, _stacked=None)Context manager to stack multiple signal handlers,
yielding a mapping ofsig=>old_handler.Parameters:sig_hnds: a mapping ofsig=>new_handleror an iterable of(sig,new_handler)pairscall_previous: optional flag (defaultFalse), passed
tosignal_handler()Functionstop(pid, signum=<Signals.SIGTERM: 15>, wait=None, do_SIGKILL=False)Stop the process specified bypid, optionally await its demise.Parameters:pid: process id.
Ifpidis a string, treat as a process id file and read the
process id from it.signum: the signal to send, defaultsignal.SIGTERM.wait: whether to wait for the process, defaultNone.
IfNone, returnTrue(signal delivered).
If0, wait indefinitely until the process exits as tested byos.kill(pid, 0).
If greater than 0, wait up towaitseconds for the process to die;
if it exits, returnTrue, otherwiseFalse;do_SIGKILL: if true (defaultFalse),
send the processsignal.SIGKILLas a final measure before return.Functionwrite_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 fromos.getpid.Release LogRelease 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 anendparameter (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: replacetraceparameter withlogger, default NoneRelease 20170908.1:
remove dependency on cs.pfxRelease 20170908:
run: pass extra keyword arguments to subprocess.callRelease 20170906.1:
Add run, pipefrom and pipeto - were incorrectly in another module.Release 20170906:
First PyPI release.