Take a Deeper Look at Clime

This page contains the details of Clime. If you just want to use Clime, you can skip this page.

About import clime.now

The content in clime.now is roughly the same as:

from clime import Program
Program().main()

If you want to customize the CLI program, see Program for more details.

Options in Docstring

The class, Command, scans the options and metavars in docstring.

Lines match the following regex will be selected.

r'*(-.+?) {2,}'

Then Clime will use this regex to parse the options and metavars from the lines selected

 r'''--?({0}) # option
    (?:
       \[?
       [= ]
       ({0})  # metavar
    )?
    ,?
 ''' \
.format('[^\s,=\[\]]+')

Some examples:

-d, --debug                enable debug mode
-q, -s, --quiet, --slient  enable slient mode
-n N, --times N            how many times do you want

Meta Variables

A meta variable also represents the type. By default, N, NUM is int. You can add the mapping of metavar and the type at Command.metatypes.

Introducing the Classes

Clime has two main classes, Command and Program.

Class Command makes a function, built-in function or bound method accpects the argument(s) from command line. Class Program scans the attributes in an object or a dict and make them into a CLI program.

The API of Clime

class clime.Program(obj=None, defcmdname=None, progname=None)

Convert a module, class or dict into a multi-command CLI program.

The obj is a module, class or dict.

The defcmdname is the default command name.

The progname is the program name that prints error (complain()).

Changed in version 0.1.4: It is almost rewritten.

complain(s)

Print s to stderr with the program name prefix

main(rawargs=None)

The main process of CLI program.

The rawargs is the arguments from command line.

If rawargs is None, it will take sys.argv[1:].

printusage(cmdname=None)

Print usage of all commands or partial command.

class clime.Command(func)

Make a function, a built-in function or a bound method accept arguments from command line.

Changed in version 0.1.4: It is almost rewritten.

static defautotype(x)

The default type auto-detection function. It use autotype by default.

execute(rawargs)

Execute this command with rawargs.

getusage(isdefault=False)

Return the usage of this command.

Example:

files [--mode VAL] [PATHS]...

If isdefault is True, it will render usage without function name.

metatypes = {'NUM': <type 'int'>, 'N': <type 'int'>}

scan(rawargs)

Scan the rawargs, and return a tuple (pargs, kargs).

rawargs can be string or list.

Uses keyword-first resolving – If keyword and positional arguments are at same place, the keyword argument takes this place and pushes the positional argument to next one.

Example:

>>> def files(mode='r', *paths):
>>>     print mode, paths
>>>
>>> files_cmd = Command(files)
>>> files_cmd.scan('--mode w f1.txt f2.txt')
(['w', 'f1.txt', 'f2.txt'], {})
>>> files_cmd('--mode w f1.txt f2.txt')
w ('f1.txt', 'f2.txt')

If an no-value options is given a function in which a default value is boolean type, it will put the opposite boolean into optargs.

If no option is given to a function in which a default value is boolean type, it will put the opposite boolean value into optargs.

>>> def test(b=True, x=None):
>>>     print b, x
>>>
>>> test_cmd = Command(test)
>>> test_cmd('-b')
False None

On the other hand, if more than one options are given to a function and

1. the default of function is boolean: it will count this options;
2. otherwise: it will put the value into a list.

>>> test_cmd('-bbb -x first -x second -x third')
3 ['first', 'second', 'third']

Changed in version 0.1.4: Use custom parser instead of getopt.

Changed in version 0.1.4: It is rewritten from Command.parse (0.1.3).

clime.helpers.autotype(s)

Automative detect the type (int, float or string) of s and convert s into it.

clime.helpers.ensureargs(args=None)

Ensure the args is a list.

return sys.argv if args is None

clime.helpers.getargspec(func)

Get the argument specification of the func.

func can be a Python function, built-in function or bound method.

It get the argument specification by parsing documentation of the function if func is a built-in function.

Changed in version 0.1.4: Remove self automatively if func is a method.

New in version 0.1.3.

clime.helpers.getoptmetas(doc)

Yield the option and the metavar in each line.

In each iteration, it will yield a list like:

[('opt1', 'META'), ('opt2', None), ...]

New in version 0.1.4.

clime.helpers.smartlyadd(a, b)

Smartly add a and b.

a	b	return
object	<any>	b
None	None	2
None	<else>	b
int	None	a+1
appendable	<any>	a.append(b); a
<else>	<any>	[a, b]

The object which is class object repersents the hyper None.

New in version 0.1.4.