Assorted process and subprocess management functions.
*Latest release 20240316*:
Fixed release upload artifacts.
Not to be confused with the excellent
(psutil)[https://pypi.org/project/psutil/] package.
## 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 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.
## 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 from `os.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 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.
## 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 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.
## Function `prep_argv(*argv)`
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.
## 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, input=None, stdin=None, **subp_options)`
Run a command via `subprocess.run`.
Return the `CompletedProcess` result or `None` if `doit` is false.
Parameters:
* `argv`: the command line to run
* `doit`: optional flag, default `True`;
if false do not run the command and return `None`
* `logger`: optional logger, default `None`;
if `True`, use `logging.getLogger()`;
if not `None` or `False` trace using `print_argv`
* `quiet`: default `True`; if false, print the command and its output
* `input`: default `None`: alternative to `stdin`;
passed to `subprocess.run`
* `stdin`: standard input for the subprocess, default `subprocess.DEVNULL`;
passed to `subprocess.run`
* `subp_options`: optional mapping of keyword arguments
to pass to `subprocess.run`
Note that `argv` is passed through `prep_argv` before use,
allowing direct invocation with conditional parts.
See the `prep_argv` function for details.
## 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`: 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`
## 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 of `sig`=>`new_handler`
or an iterable of `(sig,new_handler)` pairs
* `call_previous`: optional flag (default `False`), passed
to `signal_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.
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.
## 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 from `os.getpid`.
# Release Log
*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.
Raw data
{
"_id": null,
"home_page": "",
"name": "cs.psutils",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python2,python3",
"author": "",
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/41/eb/b41f75903d113774d4bf35d5ab5ebc04b186d49c7cceded5d067f969a1ca/cs.psutils-20240316.tar.gz",
"platform": null,
"description": "Assorted process and subprocess management functions.\n\n*Latest release 20240316*:\nFixed release upload artifacts.\n\nNot to be confused with the excellent\n(psutil)[https://pypi.org/project/psutil/] package.\n\n## Function `groupargv(pre_argv, argv, post_argv=(), max_argv=None, encode=False)`\n\nDistribute the array `argv` over multiple arrays\nto fit within `MAX_ARGV`.\nReturn a list of argv lists.\n\nParameters:\n* `pre_argv`: the sequence of leading arguments\n* `argv`: the sequence of arguments to distribute; this may not be empty\n* `post_argv`: optional, the sequence of trailing arguments\n* `max_argv`: optional, the maximum length of each distributed\n argument list, default from `MAX_ARGV`: `131072`\n* `encode`: default `False`.\n If true, encode the argv sequences into bytes for accurate tallying.\n If `encode` is a Boolean,\n encode the elements with their .encode() method.\n If `encode` is a `str`, encode the elements with their `.encode()`\n method with `encode` as the encoding name;\n otherwise presume that `encode` is a callable\n for encoding each element.\n\nThe returned argv arrays will contain the encoded element values.\n\n## Function `PidFileManager(path, pid=None)`\n\nContext manager for a pid file.\n\nParameters:\n* `path`: the path to the process id file.\n* `pid`: the process id to store in the pid file,\n default from `os.etpid`.\n\nWrites the process id file at the start\nand removes the process id file at the end.\n\n## Function `pipefrom(argv, *, quiet=False, text=True, stdin=-3, **popen_kw)`\n\nPipe text (usually) from a command using `subprocess.Popen`.\nReturn the `Popen` object with `.stdout` as a pipe.\n\nParameters:\n* `argv`: the command argument list\n* `quiet`: optional flag, default `False`;\n if true, print the command to `stderr`\n* `text`: optional flag, default `True`; passed to `Popen`.\n* `stdin`: optional value for `Popen`'s `stdin`, default `DEVNULL`\nOther keyword arguments are passed to `Popen`.\n\nNote that `argv` is passed through `prep_argv` before use,\nallowing direct invocation with conditional parts.\nSee the `prep_argv` function for details.\n\n## Function `pipeto(argv, *, quiet=False, **kw)`\n\nPipe text to a command.\nOptionally trace invocation.\nReturn the Popen object with .stdin encoded as text.\n\nParameters:\n* `argv`: the command argument list\n* `trace`: if true (default `False`),\n if `trace` is `True`, recite invocation to stderr\n otherwise presume that `trace` is a stream\n to which to recite the invocation.\n\nOther keyword arguments are passed to the `io.TextIOWrapper`\nwhich wraps the command's input.\n\nNote that `argv` is passed through `prep_argv` before use,\nallowing direct invocation with conditional parts.\nSee the `prep_argv` function for details.\n\n## Function `prep_argv(*argv)`\n\nA trite list comprehension to reduce an argument list `*argv`\nto the entries which are not `None` or `False`\nand to flatten other entries which are not strings.\n\nThis exists ease the construction of argument lists\nwith methods like this:\n\n >>> command_exe = 'hashindex'\n >>> hashname = 'sha1'\n >>> quiet = False\n >>> verbose = True\n >>> prep_argv(\n ... command_exe,\n ... quiet and '-q',\n ... verbose and '-v',\n ... hashname and ('-h', hashname),\n ... )\n ['hashindex', '-v', '-h', 'sha1']\n\nwhere `verbose` is a `bool` governing the `-v` option\nand `hashname` is either `str` to be passed with `-h hashname`\nor `None` to omit the option.\n\n## Function `print_argv(*argv, indent='', subindent=' ', end='\\n', file=None, fold=False)`\n\nPrint an indented possibly folded command line.\n\n## Function `remove_pidfile(path)`\n\nTruncate and remove a pidfile, permissions permitting.\n\n## Function `run(argv, *, doit=True, logger=None, quiet=True, input=None, stdin=None, **subp_options)`\n\nRun a command via `subprocess.run`.\nReturn the `CompletedProcess` result or `None` if `doit` is false.\n\nParameters:\n* `argv`: the command line to run\n* `doit`: optional flag, default `True`;\n if false do not run the command and return `None`\n* `logger`: optional logger, default `None`;\n if `True`, use `logging.getLogger()`;\n if not `None` or `False` trace using `print_argv`\n* `quiet`: default `True`; if false, print the command and its output\n* `input`: default `None`: alternative to `stdin`;\n passed to `subprocess.run`\n* `stdin`: standard input for the subprocess, default `subprocess.DEVNULL`;\n passed to `subprocess.run`\n* `subp_options`: optional mapping of keyword arguments\n to pass to `subprocess.run`\n\nNote that `argv` is passed through `prep_argv` before use,\nallowing direct invocation with conditional parts.\nSee the `prep_argv` function for details.\n\n## Function `signal_handler(sig, handler, call_previous=False)`\n\nContext manager to push a new signal handler,\nyielding the old handler,\nrestoring the old handler on exit.\nIf `call_previous` is true (default `False`)\nalso call the old handler after the new handler on receipt of the signal.\n\nParameters:\n* `sig`: the `int` signal number to catch\n* `handler`: the handler function to call with `(sig,frame)`\n* `call_previous`: optional flag (default `False`);\n if true, also call the old handler (if any) after `handler`\n\n## Function `signal_handlers(sig_hnds, call_previous=False, _stacked=None)`\n\nContext manager to stack multiple signal handlers,\nyielding a mapping of `sig`=>`old_handler`.\n\nParameters:\n* `sig_hnds`: a mapping of `sig`=>`new_handler`\n or an iterable of `(sig,new_handler)` pairs\n* `call_previous`: optional flag (default `False`), passed\n to `signal_handler()`\n\n## Function `stop(pid, signum=<Signals.SIGTERM: 15>, wait=None, do_SIGKILL=False)`\n\nStop the process specified by `pid`, optionally await its demise.\n\nParameters:\n* `pid`: process id.\n If `pid` is a string, treat as a process id file and read the\n process id from it.\n* `signum`: the signal to send, default `signal.SIGTERM`.\n* `wait`: whether to wait for the process, default `None`.\n If `None`, return `True` (signal delivered).\n If `0`, wait indefinitely until the process exits as tested by\n `os.kill(pid, 0)`.\n If greater than 0, wait up to `wait` seconds for the process to die;\n if it exits, return `True`, otherwise `False`;\n* `do_SIGKILL`: if true (default `False`),\n send the process `signal.SIGKILL` as a final measure before return.\n\n## Function `write_pidfile(path, pid=None)`\n\nWrite a process id to a pid file.\n\nParameters:\n* `path`: the path to the pid file.\n* `pid`: the process id to write, defautl from `os.getpid`.\n\n# Release Log\n\n\n\n*Release 20240316*:\nFixed release upload artifacts.\n\n*Release 20240211*:\n* run: new optional input= parameter to presupply input data.\n* New prep_argv(*argv) function to flatten and trim computes argv lists; use automatically in run(), pipeot(), pipefrom().\n\n*Release 20231129*:\nrun(): default stdin=subprocess.DEVNULL.\n\n*Release 20230612*:\n* pipefrom: default stdin=DEVNULL.\n* Make many parameters keyword only.\n\n*Release 20221228*:\n* signal_handlers: bugfix iteration of sig_hnds.\n* Use cs.gimmicks instead of cs.logutils.\n* Drop use of cs.upd, fixes circular import; users of run() may need to call \"with Upd().above()\" themselves.\n\n*Release 20221118*:\nrun: do not print cp.stdout.\n\n*Release 20220805*:\nrun: print trace to stderr.\n\n*Release 20220626*:\nrun: default quiet=True.\n\n*Release 20220606*:\n* run: fold in the superior run() from cs.ebooks.\n* pipefrom,pipeto: replace trace= with quiet= like run().\n* print_argv: add an `end` parameter (used by pipefrom).\n\n*Release 20220531*:\n* New print_argv function for writing shell command lines out nicely.\n* Bump requirements for cs.gimmicks.\n\n*Release 20220504*:\nsignal_handlers: reshape try/except to avoid confusing traceback.\n\n*Release 20220429*:\n* New signal_handler(sig,handler,call_previous=False) context manager to push a signal handler.\n* New signal_handlers() context manager to stack handlers for multiple signals.\n\n*Release 20190101*:\nBugfix context manager cleanup. groupargv improvements.\n\n*Release 20171112*:\nBugfix array length counting.\n\n*Release 20171110*:\nNew function groupargv for breaking up argv lists to fit within the maximum argument limit; constant MAX_ARGV for the default limit.\n\n*Release 20171031*:\nrun: accept optional pids parameter, a setlike collection of process ids.\n\n*Release 20171018*:\nrun: replace `trace` parameter with `logger`, default None\n\n*Release 20170908.1*:\nremove dependency on cs.pfx\n\n*Release 20170908*:\nrun: pass extra keyword arguments to subprocess.call\n\n*Release 20170906.1*:\nAdd run, pipefrom and pipeto - were incorrectly in another module.\n\n*Release 20170906*:\nFirst PyPI release.\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Assorted process and subprocess management functions.",
"version": "20240316",
"project_urls": {
"URL": "https://bitbucket.org/cameron_simpson/css/commits/all"
},
"split_keywords": [
"python2",
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cd25721709b4eaaecf8f6c21df32c13225ead8d5b05d07ee88e91ff9258eace9",
"md5": "600c58333175845320e67bb610cfc8e7",
"sha256": "7d05fc62d60102f256dcb2442c3374ad96f4c1cd45eed1fdd22aeccd1098d0a0"
},
"downloads": -1,
"filename": "cs.psutils-20240316-py3-none-any.whl",
"has_sig": false,
"md5_digest": "600c58333175845320e67bb610cfc8e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9027,
"upload_time": "2024-03-16T07:00:36",
"upload_time_iso_8601": "2024-03-16T07:00:36.589655Z",
"url": "https://files.pythonhosted.org/packages/cd/25/721709b4eaaecf8f6c21df32c13225ead8d5b05d07ee88e91ff9258eace9/cs.psutils-20240316-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "41ebb41f75903d113774d4bf35d5ab5ebc04b186d49c7cceded5d067f969a1ca",
"md5": "037912435acc5429cbfbb1feed076174",
"sha256": "37be9c597e41b31e2e95ee9972217652170782d2dee2c42bebd3d6ab4ec1b169"
},
"downloads": -1,
"filename": "cs.psutils-20240316.tar.gz",
"has_sig": false,
"md5_digest": "037912435acc5429cbfbb1feed076174",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9527,
"upload_time": "2024-03-16T07:00:38",
"upload_time_iso_8601": "2024-03-16T07:00:38.641468Z",
"url": "https://files.pythonhosted.org/packages/41/eb/b41f75903d113774d4bf35d5ab5ebc04b186d49c7cceded5d067f969a1ca/cs.psutils-20240316.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 07:00:38",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "cameron_simpson",
"bitbucket_project": "css",
"lcname": "cs.psutils"
}
JSON