{"id":20548576,"url":"https://github.com/kenkundert/shlib","last_synced_at":"2026-03-13T15:39:33.913Z","repository":{"id":146202644,"uuid":"49632222","full_name":"KenKundert/shlib","owner":"KenKundert","description":"shell library","archived":false,"fork":false,"pushed_at":"2025-08-24T18:21:07.000Z","size":331,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-13T20:08:54.201Z","etag":null,"topics":["shell"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KenKundert.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-01-14T08:07:01.000Z","updated_at":"2025-08-24T18:21:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"8654ea4d-0886-4d83-aaa7-89f6d7327ce2","html_url":"https://github.com/KenKundert/shlib","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/KenKundert/shlib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fshlib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fshlib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fshlib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fshlib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KenKundert","download_url":"https://codeload.github.com/KenKundert/shlib/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fshlib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30469329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T11:00:43.441Z","status":"ssl_error","status_checked_at":"2026-03-13T11:00:23.173Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["shell"],"created_at":"2024-11-16T02:13:55.519Z","updated_at":"2026-03-13T15:39:33.890Z","avatar_url":"https://github.com/KenKundert.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"ShLib — Shell Library\n=====================\n\n.. image:: https://pepy.tech/badge/shlib/month\n    :target: https://pepy.tech/project/shlib\n\n..  image:: https://github.com/KenKundert/shlib/actions/workflows/build.yaml/badge.svg\n    :target: https://github.com/KenKundert/shlib/actions/workflows/build.yaml\n\n\n.. image:: https://img.shields.io/coveralls/KenKundert/shlib.svg\n    :target: https://coveralls.io/r/KenKundert/shlib\n\n.. image:: https://img.shields.io/pypi/v/shlib.svg\n    :target: https://pypi.python.org/pypi/shlib\n\n.. image:: https://img.shields.io/pypi/pyversions/shlib.svg\n    :target: https://pypi.python.org/pypi/shlib/\n\n:Author: Ken Kundert\n:Version: 1.8\n:Released: 2025-08-24\n\nA light-weight package with few dependencies that allows users to do \nshell-script like things relatively easily in Python. Is a natural complement to \nthe pathlib library. Pathlib does pretty much what you would like to do with \na single path; shlib does similar things with many paths at once. For example, \nwith pathlib you can remove (unlink) a single file, but with shlib you can \nremove many files at once. Furthermore, most of the features of pathlib are \nimplemented as pathlib methods, so you must convert your strings to paths before \nyou can use them. ShLib is equally comfortable with strings as with paths.\n\nWriting programs that substantially interact with the file system can be \nsurprisingly painful in Python because the code that is used to do so is spread \nover many packages and those packages are not very compatible with each other \nnor do they follow the conventions of the corresponding shell commands.\n\nThis package, shlib, attempts to address those issues by providing one package \nthat combines the commonly used utilities for interacting with the filesystem \nthat follows the conventions used by the corresponding shell commands.  \n\nIt consists of replacements for some very common Unix utilities that interact \nwith the filesystem, such as cp, mv, rm, ln, mkdir, and cd. These tend to be \nless fussy than their command line counter parts. For example, rm deletes both \nfiles and directories without distinction and will not complain if the file or \ndirectory does not exist. Similarly mkdir will create any child directories \nneeded and will not complain if the directory already exists.\n\nFinally, it provides several ways to run external programs.\n\nEach feature is designed to allow you to express your desires simply and \nefficiently without worrying too much about exceptions.\n\nMost of the functions in this package take paths to files or directories. Those \npaths may be specified either as strings or pathlib paths. Many of the functions \naccept multiple paths, and those can be specified either as an array or as \nindividual arguments. Several of the functions return either a path or \na collection of paths. These paths are returned as pathlib paths.\n\n\nInstallation\n------------\n\nUse 'pip3 install shlib' to install. Requires Python3.6 or better.\n\n\nSystem Utility Functions\n------------------------\n\nCopy (cp)\n~~~~~~~~~\n\nCopy files or directories::\n\n    cp(src, ..., dest)\n\nor::\n\n    cp([src, ...], dest)\n\nCopy all source items, whether they be files or directories to dest. If there is \nmore than one src item, then dest must be a directory and the copies will be \nplaced in that directory.  The src arguments may be strings, pathlib paths, or \ncollections of strings and paths.  The dest must be a string or path.\n\nExample:\n\n.. code-block:: python\n\n   \u003e\u003e\u003e from shlib import *\n   \u003e\u003e\u003e testdir = 'testdir'\n   \u003e\u003e\u003e rm(testdir)\n   \u003e\u003e\u003e mkdir(testdir)\n   \u003e\u003e\u003e files = cartesian_product(testdir, ['f1', 'f2'])\n   \u003e\u003e\u003e touch(files)\n   \u003e\u003e\u003e dirs = cartesian_product(testdir, ['d1', 'd2'])\n   \u003e\u003e\u003e mkdir(dirs)\n   \u003e\u003e\u003e print(sorted(str(e) for e in ls(testdir)))\n   ['testdir/d1', 'testdir/d2', 'testdir/f1', 'testdir/f2']\n\n   \u003e\u003e\u003e cp('testdir/f1', 'testdir/f4')\n   \u003e\u003e\u003e print(sorted(str(f) for f in lsf(testdir)))\n   ['testdir/f1', 'testdir/f2', 'testdir/f4']\n\n   \u003e\u003e\u003e dest1 = to_path(testdir, 'dest1')\n   \u003e\u003e\u003e mkdir(dest1)\n   \u003e\u003e\u003e cp(files, dest1)\n   \u003e\u003e\u003e print(sorted(str(f) for f in lsf(dest1)))\n   ['testdir/dest1/f1', 'testdir/dest1/f2']\n\n   \u003e\u003e\u003e cp(dirs, dest1)\n   \u003e\u003e\u003e print(sorted(str(d) for d in lsd(dest1)))\n   ['testdir/dest1/d1', 'testdir/dest1/d2']\n\n   \u003e\u003e\u003e f1, f2 = tuple(files)\n   \u003e\u003e\u003e dest2 = to_path(testdir, 'dest2')\n   \u003e\u003e\u003e mkdir(dest2)\n   \u003e\u003e\u003e cp(f1, f2, dest2)\n   \u003e\u003e\u003e print(sorted(str(f) for f in lsf(dest2)))\n   ['testdir/dest2/f1', 'testdir/dest2/f2']\n\n   \u003e\u003e\u003e dest3 = to_path(testdir, 'dest3')\n   \u003e\u003e\u003e mkdir(dest3)\n   \u003e\u003e\u003e cp([f1, f2], dest3)\n   \u003e\u003e\u003e print(sorted(str(f) for f in lsf(dest3)))\n   ['testdir/dest3/f1', 'testdir/dest3/f2']\n\n\nMove (mv)\n~~~~~~~~~\n\nMove files or directories::\n\n    mv(src, ..., dest)\n\nMove all source items, whether they be files or directories to dest. If there is \nmore than one src item, then dest must be a directory and everything will be \nplaced in that directory.  The src arguments may be strings or lists of strings.  \nThe dest must be a string.\n\n.. code-block:: python\n\n   \u003e\u003e\u003e from shlib import *\n   \u003e\u003e\u003e testdir = 'testdir'\n   \u003e\u003e\u003e rm(testdir)\n   \u003e\u003e\u003e mkdir(testdir)\n   \u003e\u003e\u003e files = cartesian_product(testdir, ['f1', 'f2'])\n   \u003e\u003e\u003e touch(files)\n   \u003e\u003e\u003e dirs = cartesian_product(testdir, ['d1', 'd2'])\n   \u003e\u003e\u003e mkdir(dirs)\n   \u003e\u003e\u003e print(sorted(str(e) for e in ls(testdir)))\n   ['testdir/d1', 'testdir/d2', 'testdir/f1', 'testdir/f2']\n\n   \u003e\u003e\u003e dest = to_path(testdir, 'dest')\n   \u003e\u003e\u003e mkdir(dest)\n   \u003e\u003e\u003e mv(files, dest)                  # move a list of files\n   \u003e\u003e\u003e print(sorted(str(f) for f in lsf(dest)))\n   ['testdir/dest/f1', 'testdir/dest/f2']\n\n   \u003e\u003e\u003e mv(dirs, dest)                   # move a list of directories\n   \u003e\u003e\u003e print(sorted(str(d) for d in lsd(dest)))\n   ['testdir/dest/d1', 'testdir/dest/d2']\n\n\nRemove (rm)\n~~~~~~~~~~~\n\nRemove files or directories::\n\n    rm(path, ...)\n\nDelete all files and directories given as arguments. Does not complain if any of \nthe items do not exist.  Each argument must be either a string or a list of \nstrings.\n\n.. code-block:: python\n\n   \u003e\u003e\u003e print(sorted(str(e) for e in ls(testdir)))\n   ['testdir/dest']\n\n   \u003e\u003e\u003e print(sorted(str(e) for e in ls(dest)))\n   ['testdir/dest/d1', 'testdir/dest/d2', 'testdir/dest/f1', 'testdir/dest/f2']\n\n   \u003e\u003e\u003e rm(lsf(dest))\n   \u003e\u003e\u003e print(sorted(str(e) for e in ls(dest)))\n   ['testdir/dest/d1', 'testdir/dest/d2']\n\n   \u003e\u003e\u003e rm(dest)\n   \u003e\u003e\u003e print(sorted(str(e) for e in ls(testdir)))\n   []\n\n   \u003e\u003e\u003e rm(testdir)\n\n\nLink (ln)\n~~~~~~~~~~~\n\nCreate a symbolic link::\n\n   ln(src, link)\n\nCreates a symbolic link *link* that points to *src*.  Each argument must be \neither a string.\n\n\nMake File (touch)\n~~~~~~~~~~~~~~~~~\n\nCreate a new empty file or update the timestamp on an existing file::\n\n   touch(path, ...)\n\nEach argument must be either a string or a list of strings.\n\n\nMake Directory (mkdir)\n~~~~~~~~~~~~~~~~~~~~~~\n\nCreate an empty directory::\n\n   mkdir(path, ...)\n\nFor each argument it creates a directory and any needed parent directories.  \nReturns without complaint if the directory already exists. Each argument must be \neither a string or a list of strings.\n\n\nChange Directory (cd)\n~~~~~~~~~~~~~~~~~~~~~\n\nChange to an existing directory::\n\n   cd(path)\n\nMakes path the current working directory.\n\nMay also be used in a *with* block::\n\n   with cd(path):\n       cwd()\n\nThe working directory returns to its original value upon leaving the *with* \nblock.\n\n\nCurrent Working Directory (cwd)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nReturns the current working directory::\n\n   path = cwd()\n\n\nMount and Unmount a Filesystem (mount)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nMount a filesystem with::\n\n   mount(path)\n\nThen unmount it with::\n\n   umount(path)\n\nYou can test to determine if a filesystem is mounted with::\n\n   is_mounted(path)\n\nMay also be used in a *with* block::\n\n   with mount(path):\n       cp(path/data, '.')\n\nThe filesystem is unmounted upon leaving the *with* block.\n\n\nList Directory (ls, lsd, lsf)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nList a directory::\n\n   ls(path, ... [\u003ckwargs\u003e])\n   lsd(path, ... [\u003ckwargs\u003e])\n   lsf(path, ... [\u003ckwargs\u003e])\n\nThe first form returns a list of all items found in a directory. The second \nreturns only the directories, and the third returns only the files.\n\nOne or more paths may be specified using unnamed arguments. The paths may be \nstrings or pathlib paths, or collections of those.  If no paths are not given, \nthe current working directory is assumed.\n\nThe remaining arguments must be specified as keyword arguments.\n\n::\n\n   select=\u003cglob-str\u003e\n\nIf *select* is specified, an item is returned only if it matches the given \npattern.  Using '\\*\\*' in *select* enables a recursive walk through a directory \nand all its subdirectories.  Using '\\*\\*' alone returns only directories whereas \n'\\*\\*/\\*' returns files and directories.\n\n::\n\n   reject=\u003cglob-str\u003e\n\nIf *reject* is specified, an item is not returned if it matches the given \npattern.\n\n::\n\n   only={'file','dir'}\n\n\nIf *only* is specified, it may be either 'file' or 'dir', in which case only \nitems of the corresponding type are returned.\n\n::\n\n    hidden=\u003cbool\u003e\n\nThe value of hidden is a boolean that indicates whether items that begin with \n'.' are included in the output. If hidden is not specified, hidden items are not \nincluded unless *select* begins with '.'.\n\nExamples::\n\n   pyfiles = lsf(select='*.py')\n   subdirs = lsd()\n   tmp_mutt = lsf('/tmp/', select='mutt-*')\n\n\nFile Permissions\n~~~~~~~~~~~~~~~~\n\nChange the file permissiongs of a file, or files, or directory, or directories::\n\n   chmod(mode, path)\n\nwhere *mode* is a three digit octal number.\n\nYou may read the permissions of a file or directory using::\n\n   mode = getmod(path)\n\n\nPaths\n-----\n\nto_path\n~~~~~~~\n\nCreate a path from a collection of path segments::\n\n   p = to_path(seg, ...)\n\nThe segments are combined to form a path. Expands a leading ~. Returns a pathlib \npath. It is generally not necessary to apply to_path() to paths being given to \nthe shlib functions, but using it gives you access to all of the various pathlib \nmethods for the path.\n\n.. code-block:: python\n\n   \u003e\u003e\u003e path = to_path('A', 'b', '3')\n   \u003e\u003e\u003e str(path)\n   'A/b/3'\n\n*to_path* returns a Path object that has been extended from the standard Python \npathlib Path object.  Specifically, it includes the following methods::\n\n   p.is_readable()   — return True if path exists and is readable\n   p.is_writable()   — return True if path exists and is writable\n   p.is_executable() — return True if path exists and is executable\n   p.is_hidden()     — return True if path exists and is hidden (name starts with .)\n   p.is_newer()      — return True if path exists and is newer than argument\n   p.path_from()     — differs from relative_to() in that returned path will not start with ..\n   p.sans_ext()      — return full path without the extension\n\nSee `extended_pathlib \u003chttps://github.com/KenKundert/extended_pathlib\u003e`_ for \nmore information.\n\n\nLeaves\n~~~~~~\n\nRecursively descend into a directory yielding paths to all of the files it \ncontains. Normally hidden files are excluded unless the *hidden* argument is \nTrue.  OSErrors found during the scan are ignored unless the *report* argument \nis specified, and if specified it must be a function that takes one argument, \nthe exception raised by the error.\n\n\nCartesian Product\n~~~~~~~~~~~~~~~~~\n\nCreate a list of paths by combining from path segments in all combinations::\n\n   cartesian_product(seg, ...)\n\nLike with to_path(), the components are combined to form a path, but in this \ncase each component may be a list. The results is the various components are \ncombined in a Cartesian product to form a list. For example:\n\n.. code-block:: python\n\n   \u003e\u003e\u003e paths = cartesian_product(['A', 'B'], ['a', 'b'], ['1', '2'])\n   \u003e\u003e\u003e for p in paths:\n   ...     print(p)\n   A/a/1\n   A/a/2\n   A/b/1\n   A/b/2\n   B/a/1\n   B/a/2\n   B/b/1\n   B/b/2\n\n\nBrace Expand\n~~~~~~~~~~~~\n\nCreate a list of paths using Bash-like brace expansion::\n\n   brace_expand(pattern)\n\n.. code-block:: python\n\n   \u003e\u003e\u003e paths = brace_expand('python{2.{5..7},3.{2..6}}')\n\n   \u003e\u003e\u003e for p in sorted(str(p) for p in paths):\n   ...     print(p)\n   python2.5\n   python2.6\n   python2.7\n   python3.2\n   python3.3\n   python3.4\n   python3.5\n   python3.6\n\n\nExecuting Programs\n------------------\n\nThe following classes and functions are used to execute external programs from \nwithin Python.\n\nCommand (Cmd)\n~~~~~~~~~~~~~\n\nA class that runs an external program::\n\n   Cmd(cmd[, modes][, env][, encoding][, log][, option_args])\n\n*cmd* may be a list or a string.\n*mode* is a string that specifies various options. The options are specified \nusing a single letter, with upper case enabling the option and lower case \ndisabling it:\n\n   |  S, s: Use, or do not use, a shell\n   |  O, o: Capture, or do not capture, stdout\n   |  E, e: Capture, or do not capture, stderr\n   |  M, m: Merge, or do not merge, stderr into stdout (M overrides E, e)\n   |  W, w: Wait, or do not wait, for command to terminate before proceeding\n\nIf a letter corresponding to a particular option is not specified, the default \nis used for that option.  In addition, one of the following may be given, and it \nmust be given last\n\n   |  ``*``: accept any output status code\n   |  N: accept any output status code equal to or less than N\n   |  M,N,...: accept status codes M, N, ...\n\nIf you do not specify the status code behavior, only 0 is accepted as normal \ntermination, all other codes will be treated as errors.  An exception is raised \nif exit status is not acceptable. By default an *OSError* is raised, however if \nthe *use_inform* preference is true, then *inform.Error* is used. In this case \nthe error includes attributes that can be used to access the *stdout*, *stderr*, \n*status*, *cmd*, and *msg*.\n\n*env* is a dictionary of environment variable and their values.\n\n*encoding* is used on the input and output streams when converting them to and\nfrom strings.\n\n*log* specifies whether details about the command should be sent to log file.\nMay be True, False, or None. If None, then behavior is set by *log_cmd*\npreference. Use of *log* requires that *Inform* package be installed.\n\n*option_args* is used when rendering command to logfile, it indicates how many\narguments each option takes.  This only occurs when *use_inform* preference is \ntrue and *Inform* package is installed.\n\nFor example, to run diff you might use::\n\n   \u003e\u003e\u003e import sys, textwrap\n   \u003e\u003e\u003e ref = textwrap.dedent('''\n   ...     line1\n   ...     line2\n   ...     line3\n   ... ''').strip()\n   \u003e\u003e\u003e test = textwrap.dedent('''\n   ...     line1\n   ...     line2\n   ... ''').strip()\n\n   \u003e\u003e\u003e ref_bytes_written = to_path('./REF').write_text(ref)\n   \u003e\u003e\u003e test_bytes_written = to_path('./TEST').write_text(test)\n\n   \u003e\u003e\u003e cat = Cmd(['cat', 'TEST'], 'sOeW')\n   \u003e\u003e\u003e cat.run()\n   0\n\n   \u003e\u003e\u003e print(cat.stdout)\n   line1\n   line2\n\n   \u003e\u003e\u003e diff = Cmd('diff TEST REF', 'sOEW1')\n   \u003e\u003e\u003e status = diff.run()\n   \u003e\u003e\u003e status\n   1\n\nUse of *O* in the modes allows access to stdout, which is needed to access the \ndifferences. Specifying *E* also allows access to stderr, which in this case is \nhelpful in case something goes wrong because it allows the error handler to \naccess the error message generated by diff. Specifying *W* indicates that run() \nshould block until diff completes. This is also necessary for you to be able to \ncapture either stdout or stderr.  Specifying 1 indicates that either 0 or 1 are \nvalid output status codes; any other code output by diff would be treated as an \nerror.\n\nIf you do not indicate that stdout or stderr should be captured, those streams \nremain connected to your TTY. You can specify a string to the run() method, \nwhich is fed to the program through stdin. If you don't specify anything the \nstdin stream for the program also remains connected to the TTY.\n\nIf you indicate that run() should return immediately without out waiting for the \nprogram to exit, then you can use the wait() and kill() methods to manage the \nexecution. For example::\n\n   diff = Cmd(['gvim', '-d', lfile, rfile], 'w')\n   diff.run()\n   try:\n       status = diff.wait()\n   except KeyboardInterrupt:\n       diff.kill()\n\nCasting the object to a string returns the command itself::\n\n   \u003e\u003e\u003e print(str(cat))\n   cat TEST\n\nIf you call run(), then you should either specify 'W' as the wait mode, or you \nshould call the wait() method. If you do not, then any string you specified as \nstdin is not applied. If your intention is to kick off a process and not wait \nfor it to finish, you should use start() instead. It also allows you to specify \na string to pass to stdin, however you cannot access stdout, stderr, or the exit \nstatus. If you specify the 'O' or 'E' modes when using start(), those outputs \nare simply discarded. This is a useful way of discarding uninteresting \ndiagnostics from the program you are calling.\n\n*Cmd* also provides the *render* method, which converts the command to a string.  \nIt takes the same optional arguments as does *render_command*.\n\n\nRun\n~~~\n\n*Run* subclasses *Cmd*. It basically constructs the process and then immediately \ncalls the run() method. It takes the same arguments as Cmd, but an additional \nargument that allows you to specify stdin for the process::\n\n   Run(cmd[, modes][, stdin][, env][, encoding])\n\nRun expect you to wait for the process to end, either by specify the 'W' mode, \nor by calling wait().  For example::\n\n   \u003e\u003e\u003e echo = Run('cat \u003e helloworld', 'SoeW', 'hello world')\n   \u003e\u003e\u003e echo.status\n   0\n\n   \u003e\u003e\u003e echo = Run(['echo', 'helloworld'], 'sOew')\n   \u003e\u003e\u003e echo.wait()\n   0\n\n   \u003e\u003e\u003e print(echo.stdout.strip())\n   helloworld\n\n\nStart\n~~~~~\n\nStart also subclasses Cmd. It is similar to Run in that it immediately executes \nthe command, but it differs in that it does not expect you to wait for the \ncommand to terminate. You may specify stdin to the command if you wish, but \nsince you are not waiting for the command to terminate you cannot access stdout, \nstderr or the exit status.  Effectively, Start() kicks off the process and then \nignores it.  You may pass wait or accept in the mode string, but they are \nignored. If you select either stdout or stderr to be captured, then are wired to \n/dev/null, meaning that the selected output is swallowed and discarded.\n\n::\n\n   \u003e\u003e\u003e cat = Start('cat helloworld', 'sOe')\n\n\nwhich\n~~~~~\n\nGiven a name, a path, and a collection of read, write, or execute flags, this \nfunction returns the locations along the path where a file or directory can be \nfound with matching flags::\n\n   which(name, path=None, flags=os.X_OK)\n\nBy default the path is specified by the PATH environment variable and the flags \ncheck whether you have execute permission.\n\n\nrender_command\n~~~~~~~~~~~~~~\n\nRender a command to a string::\n\n    render_command(cmd[, option_args][, width])\n\nConverts the command to a string.  The formatting is such that you should be \nable to feed the result directly to a shell and have command execute properly.\n\n*cmd* is the command to render. It may be a string or a list of strings.\n\n*option_args* is a dictionary.  The keys are options accepted by the command and \nthe value is the number of arguments for that option.  If an option is not \nfound, it is assumed to have 0 arguments.\n\n*width* specifies how long the string must be before it is broken into multiple \nlines.  If length of resulting line would be width or less, return as a\nsingle line, otherwise place each argument and option on separate line.\n\nIf the command is rendered as multiple lines, each argument and option is placed \non a separate line, while keeping argument to options on the same line as the \noption.  Placing each option and argument on its own line allows complicated \ncommands with long arguments to be displayed cleanly.\n\nFor example::\n\n    \u003e\u003e\u003e args = {'--dux': 2, '-d': 2, '--tux': 1}\n    \u003e\u003e\u003e print(render_command('bux --dux a b -d c d --tux e f g h', args))\n    bux --dux a b -d c d --tux e f g h\n\n    \u003e\u003e\u003e print(render_command('bux --dux a b -d c d --tux e f g h', args, width=0))\n    bux \\\n        --dux a b \\\n        -d c d \\\n        --tux e \\\n        f \\\n        g \\\n        h\n\n\nset_prefs\n~~~~~~~~~\n\nUsed to set preferences that affect the *Cmd* class. The preferences are given \nas keyword arguments.\n\n*use_inform* indicates that the *Inform* exception *Error* should be raised if \nthe exit status from a command is not acceptable. If this not given or is False, \nan OSError is raised instead.  Use of this preference requires that *Inform* be \navailable.  If *use_inform* is True, then inform.Error() is used by *Cmd* and \nits subclasses (*Run* and *Start*).\n\n*log_cmd* specifies that the command and its exit status should be written to \nthe *Inform* log file.  Use of this preference requires that *Inform* be \navailable.\n\n\nError Reporting with Inform\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe *Cmd* class and its subclasses (*Run* and *Start*) raise an `Inform \n\u003chttps://inform.readthedocs.io\u003e`_ Error if the *use_inform* preference was \nspecified. This allows for rich error reporting. In particular, the command, \nexit status, stdout and stderr are all returned with the exception and are \navailable to insert into an error message. For example::\n\n    \u003e\u003e from shlib import Run, set_prefs\n    \u003e\u003e from inform import Error\n\n    \u003e\u003e set_prefs(use_inform=True)\n\n    \u003e\u003e try:\n    ..     c = Run('sort words', 'sOEW0')\n    .. except Error as e:\n    ..     e.report(template=(\n    ..         '\"{cmd}\" exits with status {status}.\\n    {stderr}',\n    ..         '\"{cmd}\" exits with status {status}.',\n    ..     ))\n    error: \"sort words\" exits with status 2.\n        sort: cannot read: words: No such file or directory.\n\nIf command returns a non-zero exit status, an exception is raised and one of two \nerror messages are printed. The first is printed if *stderr* is not empty, and \nthe second is printed if it is.\n\nMost other functions raise an OSError upon an error.  You can use *Inform* to \nconvert this exception into a reasonable error message::\n\n    \u003e\u003e from inform import fatal, os_error\n    \u003e\u003e\n    \u003e\u003e try:\n    ..    cp(from, to)\n    .. except OSError as e:\n    ..    fatal(os_error(e))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenkundert%2Fshlib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenkundert%2Fshlib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenkundert%2Fshlib/lists"}