nix_shell_utils package

nix_shell_utils.mkdir(path)[source]

runs shell command `mkdir -p path` for a single or multiple paths.

Parameters: path (Union[str, List[str]]) – either a single path or a list of paths (which will be created by mkdir)
Return type: None

nix_shell_utils.cp(src, dest)[source]

runs shell command \cp src dest.

If src,dest are lists of strings, \cp src dest will be run with each pair of source and destination paths (up to the length of the shortest list).

Parameters

src (Union[str, List[str]]) – either a source path or a list of source paths (strings)
dest (Union[str, List[str]]) – either a destination path or a list of destination paths

Return type

None

nix_shell_utils.cd(path)[source]

changes Python current working directory, returning the previous one.

path can contain ~ or environment variables, they are expanded prior to apply the change of working directory.

Parameters: path (str) – the new Python execution folder

Returns: previous Python working directory

nix_shell_utils.rm(path)[source]

executes shell command rm -rf path,effectively removing path silently.

Parameters: path (str) – the path to remove.
Return type: None

nix_shell_utils.ln(src, dest)[source]

runs shell command ln -s src dest.

Parameters

src (str) – source path of the link
dest (str) – the path that will link to src

Return type

None

nix_shell_utils.sed(cmd, file)[source]

executes shell command `sed -i cmd file`

Parameters

cmd (str) – sed command to be executed (e.g. s/foo/bar/g)
file (str) – file where the sed command is executed in place.

Return type

CompletedProcess

nix_shell_utils.basename(path)[source]

returns the basename of the input path.

Example:

>>> basename('/home/foo/bar.py')
    ==> 'bar.py'

nix_shell_utils.stem(fname)[source]

returns the stem of the basename in the path (i.e. removes suffixes).

The stem is considered to be the part of the basename between its beginning and the first dot. (note the difference with standard library pathlib.path Example:

>>> stem('/home/foo/bar.py')
    'bar'

>>> stem('/home/foo/foo.py.old')
    'foo'

nix_shell_utils.bglob(path)[source]

returns a list of the basenames resulting from globbing path.

Assume folder /home/foo contains files a.txt, b.log, c.txt

Examples:

>>> bglob('/home/foo/*.txt')
==> ['a.txt', 'c.txt']

>>> bglob('/home/foo/a*')
==> ['a.txt']

Parameters: path (str) –

nix_shell_utils.aglob(path)[source]

returns a list of absolute paths resulting from globbing path.

Examples(Assume folder /home/foo contains files a.txt, b.log, c.txt):

>>> cd('/home/foo')
>>> bglob('*.txt')
==> ['/home/foo/a.txt', '/home/foo/c.txt']

>>> bglob('a*')
==> ['/home/foo/a.txt']

Parameters: path (str) –
Return type: List[str]

nix_shell_utils.root_files(files, root)[source]

takes a list of files, and prepends them with a root path.

Example:

>>> flist = ['a.txt', 'b.txt', 'c.log']
>>> root_files(flist, '/home/foo/bar'
==> ['/home/foo/bar/a.txt', '/home/foo/bar/b.txt', '/home/foo/bar/c.log']

Parameters

files (List[str]) – list of files to be prepended by the root path
root (str) – : the root path files are prepended by.

Return type

List[str]

Returns: a list of files prepended by the root path.

nix_shell_utils.pj(*paths, leaf=True)[source]

join a number of paths into a single one.

Examples:

>>> pj('/home/foo', 'bar', 'a.txt')
==> '/home/foo/bar/a.txt'`

Parameters

paths (str) –
leaf (bool) –

Return type

str

nix_shell_utils.pwd()[source]

short hand for os.getcwd().

Return type: str

nix_shell_utils.runc(cmd, echo=True, blocking=False)[source]

runs the shell command cmd in console mode.

runc is a wrapper of subprocess.run with the following defaults:

by default, it prints the shell command executed in stdout
it prints the outputs and errors of the commmand in stdout and stderr
it returns the results return code of the command.

Parameters

cmd (str) – the command by the sh shell.
echo (bool) – if True, cmd is printed in stdout.
blocking (bool) – if True, a CalledProcessError exception is thrown if the command fails (return code different from 0).

Returns

the return code of the shell command executed.

Return type

int

nix_shell_utils.source(filename)[source]

Parameters: filename (str) –
Return type: None

nix_shell_utils.run(cmd, blocking=False, quiet=True)[source]

runs a shell command with a subprocess.run wrapper with sensible defaults.

Example:

>>> c = run('cpu-info')
cpu-info
Packages:
        0: Intel Celeron 6305
Microarchitectures:
        2x unknown
Cores:
        0: 1 processor (0), Intel unknown
        1: 1 processor (1), Intel unknown
Logical processors (System ID):
        0 (0): APIC ID 0x00000000
        1 (1): APIC ID 0x00000002

>>> print(c.stdout)
Packages:
        0: Intel Celeron 6305
Microarchitectures:
        2x unknown
Cores:
        0: 1 processor (0), Intel unknown
        1: 1 processor (1), Intel unknown
Logical processors (System ID):
        0 (0): APIC ID 0x00000000
        1 (1): APIC ID 0x00000002

>>> print(c.returncode)
0

Parameters

cmd (str) – the command to be run
blocking (bool) – if True, an exception is thrown if the command exit code != 0
quiet (bool) – if False, stdout, stderr and an echo of the command executed is printed.

Return type

CompletedProcess

Returns: a :class:subprocess.CompletedProcess object containing exit code, and the command executed (at least).

nix_shell_utils.lrun(*cmds, blocking=False, quiet=True)[source]

Parameters

cmds (str) –
blocking (bool) –
quiet (bool) –

Return type

List[CompletedProcess]

nix_shell_utils.runopt(cmd, blocking=False, quiet=True)[source]

runs a shell command with a subprocess.run wrapper with sensible defaults.

Example:

>>> c = run('cpu-info')
cpu-info
Packages:
        0: Intel Celeron 6305
Microarchitectures:
        2x unknown
Cores:
        0: 1 processor (0), Intel unknown
        1: 1 processor (1), Intel unknown
Logical processors (System ID):
        0 (0): APIC ID 0x00000000
        1 (1): APIC ID 0x00000002

>>> print(c.stdout)
Packages:
        0: Intel Celeron 6305
Microarchitectures:
        2x unknown
Cores:
        0: 1 processor (0), Intel unknown
        1: 1 processor (1), Intel unknown
Logical processors (System ID):
        0 (0): APIC ID 0x00000000
        1 (1): APIC ID 0x00000002

>>> print(c.returncode)
0

Parameters

cmd (str) – the command to be run
blocking (bool) – if True, an exception is thrown if the command exit code != 0
quiet (bool) – if False, stdout, stderr and an echo of the command executed is printed.

Return type

CompletedProcess

Returns: a :class:subprocess.CompletedProcess object containing exit code, and the command executed (at least).

nix_shell_utils.tmpenv(*remove, **update)[source]

context manager to temporarily update the os.environ shell environment in place.

Example:

with tmpenv('HOME', FOO='BAR', FOOD='SPAM'):
    print('HOME' in os.environ.keys) # => False
    print(os.environ['FOO']) # => 'BAR'
    print(os.environ['FOOD']) # => 'SPAM'

print('HOME' in os.environ.keys) # => True
print('FOO' in os.environ.keys) # => False
print('FOOD' in os.environ.keys) # => False

The os.environ dictionary is updated in-place so that the modification is sure to work in all situations.

Parameters

remove (str) – environment variable to remove
update (str) – environment variables and values to add/update

nix_shell_utils.expand(cmd)[source]

expands environment variables and home (~) from the input command/path.

Examples (assume username = mario)

>>> expand('/home/${USER}/prj')
==> '/home/mario/prj'

>>> expand('~/prj')
==> '/home/mario/prj'

>>> expand('$HOME/prj')
==> '/home/mario/prj'

>>> expand(['$HOME/prj', '~/prj'])
==> ['/home/mario/prj', '/home/mario/prj']

Parameters: cmd (Union[str, List[str]]) – either a string to be expanded or a list of strings to be expanded.
Return type: Union[str, List[str]]

Returns: if cmd was a string, it returns the expanded string. If cmd was: a list of strings, it returns a list of expanded strings.