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'>
append_to_file(filename, fd=1)

Append this command’s output to a file.

Parameters:
  • filename – Filename to append to
  • fd – File descriptor to redirect to file
Returns:

Operation

>>> clom.ls.append_to_file('list.txt')
'ls >> list.txt'

>>> clom.ls.append_to_file('list.txt', arg.STDERR)
'ls 2>> list.txt'
background()

Run the command in the background and don’t block for output.

>>> clom.ls.background()
'nohup ls &'
from_file(filename)[source]

Read a file’s contents with this command’s stdin.

Parameters:filename – The filename to read input from
Returns:Command
>>> clom.cat.from_file('list.txt')
'cat < list.txt'
hide_output(fd=1)

Redirect a command’s file descriptors to /dev/null.

Parameters:fd – File descriptor to redirect to /dev/null
Returns:Operation
>>> clom.cat.hide_output()
'cat > /dev/null'

>>> clom.cat.hide_output(STDERR)
'cat 2> /dev/null'
output_to_file(filename, fd=1)

Replace a file’s contents with this command’s output.

Parameters:
  • filename – Filename to append to
  • fd – File descriptor to redirect to file
Returns:

Operation

>>> clom.ls.output_to_file('list.txt')
'ls > list.txt'

>>> clom.ls.output_to_file('list.txt', STDERR)
'ls 2> list.txt'
pipe_to(to_cmd)

Pipe this command to another.

Parameters:to_cmd – Operation or Command to pipe to
Returns:Operation
>>> clom.ls.pipe_to(clom.grep)
'ls | grep'
redirect(from_fd, to_fd)

Redirect a command’s file descriptors.

Parameters:
  • from_fd – File descriptor to redirect from
  • to_fd – File descriptor to redirect to
Returns:

Operation

>>> clom.cat.redirect(STDERR, STDOUT)
'cat 2>&1'
with_args(*args)[source]

Arguments to call the command with.

Parameters:args – A list of arguments to pass to the command. Arguments are by automatically escaped as a clom.arg.LiteralArg unless you pass in a clom.arg.RawArg.
Returns:Command
>>> clom.echo("don't test me")
'echo 'don'\''t test me''
with_env(**kwargs)

Run the operation with environmental variables.

Parameters:kwargs – dict - Environmental variables to run command with
with_opts(*args, **kwargs)[source]

Options to call the command with.

Parameters:
  • kwargs – A dictionary of options to pass to the command. Keys are generated as –name value or -n value depending on the length.
  • args – A list of options to pass to the command. Args are only escaped, no other special processing is done.
Returns:

Command

>>> clom.curl.with_opts('--basic', f=True, header='X-Test: 1')
'curl --basic --header 'X-Test: 1' -f'
class clom.command.Operation[source]

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

append_to_file(filename, fd=1)[source]

Append this command’s output to a file.

Parameters:
  • filename – Filename to append to
  • fd – File descriptor to redirect to file
Returns:

Operation

>>> clom.ls.append_to_file('list.txt')
'ls >> list.txt'

>>> clom.ls.append_to_file('list.txt', arg.STDERR)
'ls 2>> list.txt'
background()[source]

Run the command in the background and don’t block for output.

>>> clom.ls.background()
'nohup ls &'
hide_output(fd=1)[source]

Redirect a command’s file descriptors to /dev/null.

Parameters:fd – File descriptor to redirect to /dev/null
Returns:Operation
>>> clom.cat.hide_output()
'cat > /dev/null'

>>> clom.cat.hide_output(STDERR)
'cat 2> /dev/null'
output_to_file(filename, fd=1)[source]

Replace a file’s contents with this command’s output.

Parameters:
  • filename – Filename to append to
  • fd – File descriptor to redirect to file
Returns:

Operation

>>> clom.ls.output_to_file('list.txt')
'ls > list.txt'

>>> clom.ls.output_to_file('list.txt', STDERR)
'ls 2> list.txt'
pipe_to(to_cmd)[source]

Pipe this command to another.

Parameters:to_cmd – Operation or Command to pipe to
Returns:Operation
>>> clom.ls.pipe_to(clom.grep)
'ls | grep'
redirect(from_fd, to_fd)[source]

Redirect a command’s file descriptors.

Parameters:
  • from_fd – File descriptor to redirect from
  • to_fd – File descriptor to redirect to
Returns:

Operation

>>> clom.cat.redirect(STDERR, STDOUT)
'cat 2>&1'
with_env(**kwargs)[source]

Run the operation with environmental variables.

Parameters:kwargs – dict - Environmental variables to run command with

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.

Project Versions

Table Of Contents

Previous topic

Python Clom

This Page