Clom API

clom

The main interface to clom is the clom object:

>>> from clom import clom
>>> clom.cat
'cat'

Each attribute of the clom object is a clom.command.Command.

clom.clom

Manager for generating commands.

clom.NOTSET

Represents an argument that is not set as opposed to None which is a valid value

clom.STDIN

Standard In file descriptor

clom.STDOUT

Standard Out file descriptor

clom.STDERR

Standard Error file descriptor

class clom.AND(*commands)

Combine commands together that must execute together.

Parameters:commands – List of Commands or Operations to combine

>>> from clom import clom
>>> AND(clom.echo('foo'), clom.echo('bar'))
'( echo foo && echo bar )'

class clom.OR(*commands)

Combine commands together that must not execute together.

Parameters:commands – List of Commands or Operations to combine

>>> from clom import clom
>>> OR(clom.echo('foo'), clom.echo('bar'))
'( echo foo || echo bar )'

Commands

class clom.command.Command(clom, name, parent=None)

A command line command.

Don’t use directly, instead use a clom object.

>>> from clom import clom
>>> type(clom.cat)
<class 'clom.command.Command'>

as_string(*args, **kwargs)

Shortcut for command.with_opts(**kwargs).with_args(*args)

Returns:str - Command suitable to pass to the command line

shell

Returns a Shell that will allow you to execute commands on the shell.

class clom.command.Operation

Base class for all command line operations, functions, commands, etc.

as_string()

Returns:str - Command suitable to pass to the command line

shell

Returns a Shell that will allow you to execute commands on the shell.

Shell

class clom.shell.Shell(cmd)

Easily run `Command`s on the system’s shell.

all(*args, **kwargs)

Executes the command and returns a list of the lines of the result.

Alias for shell(...).all()

>>> str(clom.echo.shell.all('foo\nfoobar'))
"['foo', 'foobar']"

execute(*args, **kwargs)

Execute the command on the shell without capturing output.

Use this if the result is very large or you do not care about the results.

Raises:CommandError Returns:CommandResult

first(*args, **kwargs)

Executes the command and returns the first line. Commands with no output return empty-string.

Alias for shell(...).first()

>>> clom.echo.shell.first('foo\nfoobar')
'foo'

>>> clom.true.shell.first()
''

iter(*args, **kwargs)

Executes the command and returns an iterator of the results.

Alias for shell(...).iter()

last(*args, **kwargs)

Executes the command and returns the last line.

Alias for shell(...).last()

>>> str(clom.echo.shell.last('foo\nfoobar'))
'foobar'

class clom.shell.CommandError(return_code, stdout, stderr, message)

An error returned from a shell command.

class clom.shell.CommandResult(return_code, stdout='', stderr='')

The result of a command execution.

all(strip=True)

Get all lines of the results as a list.

code

Alias to return_code

first(strip=True)

Get the first line of the results.

You can also get the return code:

>>> r = CommandResult(2)
>>> r.first().return_code
2

iter(strip=True)

Iterate over the command results split by lines with whitespace optionally stripped.

Parameters:strip – bool - Strip whitespace for each line

last(strip=True)

Get the last line of the results.

You can also get the return code:

>>> r = CommandResult(2)
>>> r.last().return_code
2

return_code

Returns the status code returned from the command.

stderr

Returns the command’s stderr as a string.

stdout

Returns the command’s stdout as a string.

Arguments

class clom.arg.RawArg(data)

A command line argument that is not escaped at all.

class clom.arg.LiteralArg(data)

A command line argument that is fully escaped.

Use this if you want the value to be maintained and not interpolated.

Chars like * and $ are escaped and the value is wrapped in quotes.

See also

http://www.gnu.org/software/bash/manual/bashref.html#Single-Quotes