shil 2023.8.22.21.20

Shell helper utilities for python

shil
	Shell-util library for python. Includes helpers for subprocess invocation, shell-formatters / pretty-printers, and more.

---

• Overview
• Features
• Installation
• Usage
• CLI Usage
• API Usage
  • OOP-style Dispatch
  • Functional approach to dispatch
  • Loading data when command-output is JSON
  • Serialization with Pydantic
  • Caller determines logging
  • Rich-console Support
  • Stay DRY with Runners

---

Overview

The shil library provides various shell-utilities for python.

Features

• Helpers for subprocess invocation
• Shell-formatters / pretty-printers
• A somewhat usable parser / grammar for bash
• Console support for rich & rich protocols

---

Installation

See pypi for available releases.

pip install shil

---

Usage

CLI Usage

The shil library publishes a small CLI tool, mostly just for testing & demoing the API behaviour. See the CLI docs for the latest (autogenerated) help.

API Usage

See also:

• the unit-tests for some examples of library usage
• the smoke-tests for example usage of stand-alone scripts

OOP-style Dispatch

This uses shil.Invocation and returns shil.InvocationResponse.

>>> import shil 
>>> req = cmd = shil.Invocation(command='printf hello-world\n')
>>> resp = cmd()
>>> print(resp.stdout)
hello-world
>>>

Functional approach to dispatch

Use shil.invoke, get back shil.InvocationResponse

>>> import shil 
>>> resp = shil.invoke(command='printf hello-world\n')
>>> print(resp.stdout)
hello-world
>>>

Loading data when command-output is JSON

>>> import shil 
>>> cmd = shil.Invocation(command="""echo '{"foo":"bar"}'""", load_json=True)
>>> resp = cmd()
>>> print(resp.data)
{'foo': 'bar'}
>>> assert type(resp.data) == type({})
>>> assert resp.data['foo'] == 'bar'
>>>

Serialization with Pydantic

>>> import json, shil 
>>> req = cmd = shil.Invocation(command="""echo pipes-are-allowed|grep allowed""")
>>> resp = cmd()
>>> keys = resp.dict().keys()
>>> expected = 'stdout stderr failed failure success succeeded data'.split()
>>> assert all([k in keys for k in expected])
>>>

Caller determines logging

Works like this with basic logger:

>>> import logging, shil 
>>> logger = logging.getLogger()
>>> resp = shil.invoke('ls /tmp', command_logger=logger.critical, output_logger=logger.warning)
>>>

Supports using rich-logger too:

>>> import shil 
>>> from rich.console import Console 
>>> console = Console(stderr=True)
>>> resp = shil.invoke('ls /tmp', command_logger=console.log)
>>>

Rich-console Support

Besides using rich-logger as above, you can use the rich-protocol more directly.

Printing works the way you'd expect for Invocation and InvocationResponse.

import rich

import shil

req = cmd = shil.Invocation(command='echo {"foo":"bar"}')
resp = cmd()
rich.print(req)
rich.print(resp)

Stay DRY with Runners

Runner's are basically just partials on shil.invoke. It's simple but this can help reduce copying around repetitive configuration.

>>> import shil 
>>> from rich.console import Console 
>>> console=Console(stderr=True)
>>> runner = shil.Runner(output_logger=console.log, command_logger=console.log)
>>> resp = runner('ls /tmp')
>>> assert isinstance(resp,(shil.InvocationResult,))
>>>