Python ClomĀ¶

AboutĀ¶

Clom is a Python Command Line Object Mapper. It’s intended to make generating commands and escaping arguments easier for command line interaction. It’s particularly useful when used with Fabric or subprocess.

InstallationĀ¶

Install with pip or easy_install.

pip install clom

Usage ExamplesĀ¶

Import:

>>> from clom import clom

Build a command:

>>> clom.echo("Don't test me")
"echo 'Don'\\''t test me'"

Augment with arguments:

>>> clom.ls.with_opts('-a', '-t', l=True).with_args('~/')
"ls -a -t -l '~/'"
>>> clom.curl('http://dev.host', X='POST', data='message=hello')
'curl -X POST --data message=hello http://dev.host'

Use sub commands:

>>> clom.git.checkout('mybranch')
'git checkout mybranch'

Execute with ease:

>>> clom.seq(5).shell.all()
['1', '2', '3', '4', '5']

>>> clom.seq.shell('5').first()
'1'

Iterate over results:

>>> for i in clom.seq(3).shell():
...     print(i)
...
1
2
3

Handle errors:

>>> clom.touch('/not/a/thing').shell()      
Traceback (most recent call last):
  ...
CommandError: Error while executing "touch /not/a/thing" (1):
touch: cannot touch ā€˜/not/a/thingā€™: No such file or directory

Group commands:

>>> from clom import AND, OR
>>> OR(clom.vagrant.up, clom.echo('Vagrant up failed'))
"( vagrant up || echo 'Vagrant up failed' )"
>>> OR(clom.vagrant.up, clom.echo('Vagrant up failed')).shell()
<CommandResult return_code=0, stdout=18 bytes, stderr=... bytes>
>>> print(OR(clom.false, clom.echo('Vagrant up failed')).shell())
Vagrant up failed

Re-use commands:

>>> echo = clom.echo
>>> echo.one.two
'echo one two'
>>> echo.three.four.shell.all()
['three four']
>>> echo.foo.bar.shell.all()
['foo bar']

Background tasks:

>>> clom.VBoxHeadless.with_opts(startvm="Windows Base").background()
"nohup VBoxHeadless --startvm 'Windows Base' &> /dev/null &"
>>> clom.VBoxHeadless.with_opts(startvm="Windows Base").background().shell()
<CommandResult return_code=0, stdout=0 bytes, stderr=0 bytes>

>>> vbox.list.runningvms.shell.all()            
['"Windows Base" {949ec0af-92d0-4140-8a6c-36301ca6f695}']

Works great with fabric:

>>> from fabric.api import run, local           
>>> local(clom.ls)                              
[localhost] local: ls
clom            clom.egg-info   docs            nohup.out       tests
''

Can even create fab commands:

>>> clom.fab.test('doctest', 'unit').deploy('dev')
'fab test:doctest,unit deploy:dev'
>>> clom.fab.with_opts('-a', hosts='dev.host').deploy.with_args('dev','test')
'fab -a --hosts dev.host deploy:dev,test'

API DocumentationĀ¶

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)[source]Ā¶

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)[source]Ā¶

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[source]Ā¶

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

as_string()[source]Ā¶
Returns:str - Command suitable to pass to the command line
shell[source]Ā¶

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

ShellĀ¶

class clom.shell.Shell(cmd)[source]Ā¶

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

all(*args, **kwargs)[source]Ā¶

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)[source]Ā¶

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)[source]Ā¶

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)[source]Ā¶

Executes the command and returns an iterator of the results.

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

last(*args, **kwargs)[source]Ā¶

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)[source]Ā¶

An error returned from a shell command.

class clom.shell.CommandResult(return_code, stdout='', stderr='')[source]Ā¶

The result of a command execution.

all(strip=True)[source]Ā¶

Get all lines of the results as a list.

code[source]Ā¶

Alias to return_code

first(strip=True)[source]Ā¶

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)[source]Ā¶

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

Parameters:strip – bool - Strip whitespace for each line
last(strip=True)[source]Ā¶

Get the last line of the results.

You can also get the return code:

>>> r = CommandResult(2)
>>> r.last().return_code
2
return_code[source]Ā¶

Returns the status code returned from the command.

stderr[source]Ā¶

Returns the command’s stderr as a string.

stdout[source]Ā¶

Returns the command’s stdout as a string.

ArgumentsĀ¶

class clom.arg.RawArg(data)[source]Ā¶

A command line argument that is not escaped at all.

class clom.arg.LiteralArg(data)[source]Ā¶

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.