Cogs - Toolkit for developing command-line utilities in Python

Overview

Cogs is a toolkit for developing command-line utilities in Python. It
handles common operations such as parsing command-line parameters,
dispatching commands and loading configuration files. It is targeted to
developers, sysadmins, testers, or anyone who needs to script their
routine tasks.

Cogs is a free software licensed under MIT license. Cogs is written by
Kirill Simonov from Prometheus Research, LLC.

Getting Started

This operation installs a command-line utility cogs and a Python
package of the same name. The cogs utility is a dispatcher which
which lets you select and execute your scripts (called tasks). Let us
show how to do it with a simple example.

In the current directory, create a file cogs.local.py with the
following content:

Cogs converts function Hello() into a command-line script with
parameters inferred from the function signature, so then when you
execute a command cogs hello world, you invoke a function
Hello('world').

Loading Extensions

In this section, we describe how Cogs finds and loads extensions.

Cogs loads extensions from two places:

cogs.local.py or cogs.local/__init__.py module in the current
directory;

all Python packages under cogs.extensions entry point.

The easiest way to add an extension is to create a cogs.local.py
module and add your tasks there. If you want to split the module into
multiple files, create a cogs.local subdirectory with an
__init__.py module. cogs.local.py or cogs.local/__init__.py
are executed by Cogs on startup. The modules must be owned by the same
user who runs the cogs script, or by root; otherwise they are
ignored.

If you need to package and distribute your Cogs extensions, using
cogs.local may be inconvenient. In this case, you may package your
Cogs extensions as a regular Python distribution.

Suppose we want to pack the hello task as a separate package.
Create a directory tree with the following structure:

Cogs-Hello/
src/
cogs/
__init__.py
hello.py
setup.py

The file cogs/hello.py contains the definition of the hello task
and has the same content as cogs.local.py in our previous example.

The file cogs/__init__.py contains just one line:

__import__('pkg_resources').declare_namespace(__name__)

The file setup.py contains the meta-data of the package and may
look like this:

Note the parameter entry_points in setup() invocation; it adds
an entry point cogs.extensions named Hello that refers to module
cogs.hello. On startup, Cogs finds and loads all packages defined
for the entry point cogs.extensions.

Defining Tasks

A task can be created from a function or a class by augmenting it with
the task decorator:

Cogs uses the name of the function or the class as the task identifier.
The name is normalized: it is converted to lower case and has all
underscore characters converted to the dash symbol.

If the task is derived from a function, the task arguments are inferred
from the function signature. Cogs executes such task by calling the
function with the parsed command-line parameters.

If the task is derived from a class, the task arguments and options must
be defined using argument() and option() descriptors. To
execute a task, Cogs creates an instance of the class passing the task
parameters as the constructor arguments. Then Cogs invokes the
__call__ method of the instance. Thus the call of:

$ cogs factorial 10

is translated to:

Factorial('10')

and the call of:

$ cogs fibonacci 10

is translated to:

t = Fibonacci(10)
t()

The docstring of the function or the class becomes the task
description:

You can execute this task with option --output or -o to redirect
the output to a file:

$ cogs write-hello world -o hello.txt

Configuration and Environment

Cogs allows you to define custom configuration parameters. For example:

from cogs import env, task, setting
import os
@setting
def Default_Name(name=None):
"""the name to use for greetings (if not set: login name)"""
if name is None or name == '':
name = os.getlogin()
if not isinstance(name, str):
raise ValueError("a string value is expected")
env.add(default_name=name)
@task
def Hello_With_Configuration(name=None):
if name is None:
name = env.default_name
print "Hello, %s!" % name.capitalize()

Now you could specify the name as a configuration parameter
default-name. One way to do it is to use global option
--default-name:

$ cogs --default-name=world hello-with-configuration

You could also pass a configuration parameter using an environment
variable:

$ COGS_DEFAULT_NAME=world cogs hello-with-configuration

Alternatively, you can put parameters to a configuration file. In the
current directory, create a file cogs.conf with the following
content:

default-name: world

Now run:

$ cogs hello-with-configuration

Cogs reads configuration from the following locations:

/etc/cogs.conf

$PREFIX/etc/cogs.conf

$HOME/.cogs/cogs.conf

./cogs.conf

program environment

command-line parameters

If you'd like to specify the usage of a configuration file that is in a
different location than the standard locations listed above, you can use
the global option --config as follows:

$ cogs --config=alternate-cogs.conf hello-with-configuration

To create a new configuration parameter, wrap a function named after the
parameter with the Setting dasfdsaf decorator. The function must accept
zero or one argument: the function is called without arguments if the
parameter is not specified explicitly, and is called with the value of
the parameter is it was set using one of the methods described above.

Cogs does not impose any rules on what to do with the parameter value,
but we recommend to store the value in the global env variable. The
call of env.add(default_name=name) adds a new parameter
default_name which could then be accessed as env.default_name.

API Reference

cogs.core

Classes and functions defined in cogs.core are also importable from
the cogs package.

The Setting dasfdsaf decorator converts the wrapped function to a
configuration parameter, which properties are inferred from the
function attributes.

The setting name is generated from the function name. The name is
converted to lower case and has all underscores replaced with
dashes.

The setting documentation is generated from the function docstring.

The function must be able to accept zero and one parameter. The
function is called at startup with no parameters if the setting is
not explicitly set by the user; otherwise it is called with the
value of the setting. The function is responsible for storing the
value in the env object.

argument(check, default, plural=False)

Describes a task argument.

check

A function which is called to check and/or transform the
argument value. The function must return the transformed value
or raise ValueError exception on error.

default

The default value to be used if the argument is optional and not
specified. If this parameter is not set, the argument is
mandatory.

plural

If set, the argument consumes all the remaining command-line
parameters. Must be the last argument specified.

option(key, check, default, plural=False, value_name=None, hint=None)

Describes a task option.

key

A one-character shorthand.

check

A function called to check and transform the value of the
option. The function must return the transformed value or raise
ValueError exception on error.

default

The default value used when the option is not specified. If
this parameter is not set, the option does not accept a value.
Such an option is treated is a toggle and takes a value True
if set and False if not set.

plural

If set, indicates that the option could be specified more than
once.

value_name

The preferred name for the option value; used for the task
description.

hint

A one-line description of the option; used for the task
description.

env

A global object that keeps values of configuration parameters and
other properties.

env.add(**keywords)

Add new parameters.

env.set(**keywords)

Set values for existing parameters.

env.push(**keywords)

Save the current state and set new values for existing
parameters.

env.pop()

Restore a previously saved state of parameters and values.

env(**keywords)

A context manager for with statement. On entering, saves
the current state and sets new parameter values. On exiting,
restores the saved state.

cogs.log

Printing utilities.

log(msg="", *args, **kwds)

Print the message to the standard output.

If extra positional or keyword arguments are given, they are
formatted with format() function using msg as the template.