Assorted process and subprocess management functions.
Project description
Assorted process and subprocess management functions.
Latest release 20230612:
- pipefrom: default stdin=DEVNULL.
- Make many parameters keyword only.
Function 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 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: MAX_ARGVencode
: default False. If true, encode the argv sequences into bytes for accurate tallying. Ifencode
is a Boolean, encode the elements with their .encode() method. Ifencode
is astr
, encode the elements with their.encode()
method withencode
as the encoding name; otherwise presume thatencode
is a callable for encoding each element.
The returned argv arrays will contain the encoded element values.
Function 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 fromos.etpid
.
Writes the process id file at the start and removes the process id file at the end.
Function pipefrom(argv, *, quiet=False, 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 listquiet
: optional flag, defaultFalse
; if true, print the command tostderr
text
: optional flag, defaultTrue
; passed toPopen
.stdin
: optional value forPopen
'sstdin
, defaultDEVNULL
Other keyword arguments are passed toPopen
.
Function pipeto(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
), iftrace
isTrue
, recite invocation to stderr otherwise presume thattrace
is a stream to which to recite the invocation.
Other keyword arguments are passed to the io.TextIOWrapper
which wraps the command's input.
Function print_argv(*argv, indent='', subindent=' ', end='\n', file=None, fold=False)
Print an indented possibly folded command line.
Function remove_pidfile(path)
Truncate and remove a pidfile, permissions permitting.
Function run(argv, doit=True, logger=None, quiet=True, **subp_options)
Run a command via subprocess.run
.
Return the CompletedProcess
result or None
if doit
is false.
Parameters:
argv
: the command line to rundoit
: optional flag, defaultTrue
; if false do not run the command and returnNone
logger
: optional logger, defaultNone
; ifTrue
, uselogging.getLogger()
; if notNone
orFalse
trace usingprint_argv
quiet
: defaultTrue
; if false, print the command and its outputsubp_options
: optional mapping of keyword arguments to pass tosubprocess.run
Function 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
: theint
signal 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) afterhandler
Function 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 ofsig
=>new_handler
or an iterable of(sig,new_handler)
pairscall_previous
: optional flag (defaultFalse
), passed tosignal_handler()
Function 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. Ifpid
is 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 towait
seconds for the process to die; if it exits, returnTrue
, otherwiseFalse
;do_SIGKILL
: if true (defaultFalse
), send the processsignal.SIGKILL
as a final measure before return.
Function 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 fromos.getpid
.
Release Log
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cs.psutils-20230612-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e8cec4e07cd82f76e9314716098da45f12b28469d9c4a60054c2376b9fb7d2c4 |
|
MD5 | e019de88db69c660d86012bd4ae1fb50 |
|
BLAKE2b-256 | 3edaac11090b1dbfa2032d8309cb8e8d39bfd52b6adf03350462b5accd3a435e |