lagoon

Concise layer on top of subprocess, similar to sh project.

🌐 https://pypi.org/project/lagoon/

Support

If you see an error along the lines of:

ImportError: cannot import name 'zyx' from 'lagoon.text'

This means the app requires command zyx to be available, and you don't have it on your system. The solution is to install zyx in the usual way, e.g. via your package manager.

Usage examples

Unlike with plain old subprocess, stdout is returned by default. Use the print token to send it to console:

from lagoon.text import docker

docker.run.__rm[print]('hello-world')

Attributes are treated as arguments, and their underscores are converted to dashes. Arguments in brackets are not transformed except for conversion to string. Use the partial token to suppress launch via brackets, and use with to run a command in the background:

from lagoon.text import zcat
from lagoon.program import partial # Also works when imported from functools.
import sys

with zcat[partial]('/var/log/dmesg.1.gz') as f:
    for line in f:
        sys.stdout.write(line)

When there is just one value to return it is returned directly, otherwise CompletedProcess (or Popen in background case) is returned:

from lagoon.text import echo

assert 'word\n' == echo('word')
assert 'word\n' == echo('word', check = False).stdout
assert 0 == echo('word', check = False).returncode
assert 0 == echo[print]('word', check = False)

A slice token can be used to concisely redirect one or more of stdin/stdout/stderr at once, with None (no value) meaning no change to the corresponding stream. Use sys to reset a stream to None e.g. the :sys and print tokens have the same effect, with the latter preferred as it doesn't require an import:

from lagoon.text import cat

with open('source') as f, open('dest', 'w') as g:
    cat[f:g]()

Defaults different to subprocess

• The stdout is returned instead of being sent to console
• CalledProcessError is raised if the exit status is not zero i.e. check is True
• Environment variables are merged into the existing environment instead of replacing it
  • Set a variable to None to remove it from the environment
• When importing from lagoon.text all 3 streams are in text mode, use lagoon.binary for binary mode

Irregular commands

You can use getattr if the command can't be imported in the usual way:

import lagoon.text

gplusplus = getattr(lagoon.text, 'g++')

Alternatively create a ProgramHandle manually:

from lagoon.program import Program
from shutil import which

gplusplus = Program.text(which('g++'))

Most commands are dash-separated so lagoon.text/lagoon.binary translate that to underscore for convenience. If your command already has an underscore in its name, it will be in lagoon.sic.text/lagoon.sic.binary instead:

from lagoon.text import debian_distro_info
from lagoon.sic.text import lsb_release

In the rare case a command has at least one dash, but translating its dashes to underscores would result in an unimportable name, it too will be in the sic modules:

import lagoon.sic.text

gplusplus_11 = getattr(lagoon.sic.text, 'g++-11')