The Shortcuts of Clime

It is the simplest way to convert your module into a CLI program:

import clime.now

The above line is same as to execute:

import clime
clime.start()

In this form, you can pass arguments to start() to customize your CLI program.

The most formal way is:

from clime import Program
prog = Program()
prog.main()

The only case to use this form is you want to customize arguments for your CLI program. You can do it by passing arguments to main().

The Core Module — clime.core

clime.core.start(*args, **kargs)[source]

It is same as Program(*args, **kargs).main().

Changed in version 1.0: renamed from customize to start

New in version 0.1.6.

See also

Program has the detail of arguments.

clime.core.customize(*args, **kargs)

It is same as Program(*args, **kargs).main().

Changed in version 1.0: renamed from customize to start

New in version 0.1.6.

See also

Program has the detail of arguments.

class clime.core.Program(obj=None, default=None, white_list=None, white_pattern=None, black_list=None, ignore_help=False, ignore_return=False, name=None, doc=None, debug=False)[source]

Convert a module or mapping into a multi-command CLI program.

See also

There is a shortcut of using Programstart().

Parameters:
  • obj (a module or a mapping) – an object you want to convert
  • default (str) – the default command name
  • white_list (list) – the white list of commands; By default, it will use the attribute, __all__, of a module, if it finds.
  • white_pattern (RegexObject) – the white pattern of commands; The regex should have a group named name.
  • black_list (list) – the black list of commands
  • ignore_help (bool) – Let it treat --help or -h as a normal argument.
  • ignore_return (bool) – prevents it from printing the return value.
  • name (bool) – the name of this program; It is used to show error messages. By default, it takes the first arguments from CLI.
  • doc (str) – the documentation for this program
  • debug – It will print a full traceback if it is True.

Changed in version 0.3: The -h option also triggers help text now.

New in version 0.1.9: Added white_pattern.

New in version 0.1.6: Added ignore_return.

New in version 0.1.5: Added white_list, black_list, ignore_help, doc and debug.

Changed in version 0.1.5: Renamed defcmd and progname.

Changed in version 0.1.4: It is almost rewritten.

complain(msg)[source]

Print msg with the name of this program to stderr.

main(raw_args=None)[source]

Start to parse the raw arguments and send them to a Command instance.

Parameters:raw_args (list) – The arguments from command line. By default, it takes from sys.argv.
print_usage(cmd_name=None)[source]

Print the usage(s) of all commands or a command.

class clime.core.Command(func, name=None)[source]

Make a Python function or a built-in function accepts arguments from command line.

Parameters:
  • func (Python function or built-in function) – a function you want to convert
  • name (str) – the name of this command

Changed in version 0.1.5: It is rewritten again. The API is same as the previous version, but some behaviors may be different. Please read Command.parse() for more details.

Changed in version 0.1.4: It is almost rewritten.

build_usage(without_name=False)[source]

Build the usage of this command.

Parameters:without_name (bool) – Make it return an usage without the function name.
Return type:str
cast(arg_name, val)[source]

Cast val by arg_name.

Parameters:
  • arg_name (str) – an argument name
  • val (any) – a value
Return type:

any

dealias(alias)[source]

It maps alias to an argument name. If this alias maps noting, it return alias itself.

Parameters:key (str) – an alias
Return type:str
execute(raw_args=None)[source]

Execute this command with raw_args.

Parameters:raw_args (a list or a str) – raw arguments
Return type:any
get_usage(without_name=False)

Build the usage of this command.

Parameters:without_name (bool) – Make it return an usage without the function name.
Return type:str
parse(raw_args=None)[source]

Parse the raw arguments.

Parameters:raw_args (a list or a str) – raw arguments
Return type:double-tuple: (pargs, kargs)

New in version 0.1.5.

Here are examples:

>>> def repeat(message, times=2, count=False):
...     '''It repeats the message.
...
...     -m=<str>, --message=<str>  The description of this option.
...     -t=<int>, --times=<int>
...     -c, --count
...     '''
...     s = message * times
...     return len(s) if count else s
...
>>> repeat('string', 3)
'stringstringstring'

Make a Command instance:

>>> repeat_cmd = Command(repeat)
>>> repeat_cmd.build_usage()
'repeat [-t <int> | --times=<int>] [-c | --count] <message>'
>>> repeat_cmd.execute('Hi!')
'Hi!Hi!'

You can also use options (keyword arguments) to assign arguments (positional arguments):

>>> repeat_cmd.execute('--message=Hi!')
'Hi!Hi!'
>>> repeat_cmd.execute('--message Hi!')
'Hi!Hi!'

The short version defined in docstring:

>>> repeat_cmd.execute('-mHi!')
'Hi!Hi!'
>>> repeat_cmd.execute('-m=Hi!')
'Hi!Hi!'
>>> repeat_cmd.execute('-m Hi!')
'Hi!Hi!'

It counts how many times options appear, if you don’t specify a value:

>>> repeat_cmd.execute('--times=4 Hi!')
'Hi!Hi!Hi!Hi!'
>>> repeat_cmd.execute('Hi! -tttt')
'Hi!Hi!Hi!Hi!'
>>> repeat_cmd.execute('-ttttm Hi!')
'Hi!Hi!Hi!Hi!'

However, if a default value is a boolean, it just switches the boolean value and does it only one time.

Mix them all:

>>> repeat_cmd.execute('-tttt --count Hi!')
12
>>> repeat_cmd.execute('-ttttc Hi!')
12
>>> repeat_cmd.execute('-ttttcc Hi!')
12
>>> repeat_cmd.execute('-ttccttm Hi!')
12

It is also supported to collect arbitrary arguments:

>>> def everything(*args, **kargs):
...     return args, kargs
>>> everything_cmd = Command(everything)
>>> everything_cmd.build_usage()
'everything [--<key>=<value>...] [<args>...]'
>>> everything_cmd.execute('1 2 3')
((1, 2, 3), {})
>>> everything_cmd.execute('--x=1 --y=2 --z=3')
((), {'y': 2, 'x': 1, 'z': 3})
scan(raw_args=None)

Parse the raw arguments.

Parameters:raw_args (a list or a str) – raw arguments
Return type:double-tuple: (pargs, kargs)

New in version 0.1.5.

Here are examples:

>>> def repeat(message, times=2, count=False):
...     '''It repeats the message.
...
...     -m=<str>, --message=<str>  The description of this option.
...     -t=<int>, --times=<int>
...     -c, --count
...     '''
...     s = message * times
...     return len(s) if count else s
...
>>> repeat('string', 3)
'stringstringstring'

Make a Command instance:

>>> repeat_cmd = Command(repeat)
>>> repeat_cmd.build_usage()
'repeat [-t <int> | --times=<int>] [-c | --count] <message>'
>>> repeat_cmd.execute('Hi!')
'Hi!Hi!'

You can also use options (keyword arguments) to assign arguments (positional arguments):

>>> repeat_cmd.execute('--message=Hi!')
'Hi!Hi!'
>>> repeat_cmd.execute('--message Hi!')
'Hi!Hi!'

The short version defined in docstring:

>>> repeat_cmd.execute('-mHi!')
'Hi!Hi!'
>>> repeat_cmd.execute('-m=Hi!')
'Hi!Hi!'
>>> repeat_cmd.execute('-m Hi!')
'Hi!Hi!'

It counts how many times options appear, if you don’t specify a value:

>>> repeat_cmd.execute('--times=4 Hi!')
'Hi!Hi!Hi!Hi!'
>>> repeat_cmd.execute('Hi! -tttt')
'Hi!Hi!Hi!Hi!'
>>> repeat_cmd.execute('-ttttm Hi!')
'Hi!Hi!Hi!Hi!'

However, if a default value is a boolean, it just switches the boolean value and does it only one time.

Mix them all:

>>> repeat_cmd.execute('-tttt --count Hi!')
12
>>> repeat_cmd.execute('-ttttc Hi!')
12
>>> repeat_cmd.execute('-ttttcc Hi!')
12
>>> repeat_cmd.execute('-ttccttm Hi!')
12

It is also supported to collect arbitrary arguments:

>>> def everything(*args, **kargs):
...     return args, kargs
>>> everything_cmd = Command(everything)
>>> everything_cmd.build_usage()
'everything [--<key>=<value>...] [<args>...]'
>>> everything_cmd.execute('1 2 3')
((1, 2, 3), {})
>>> everything_cmd.execute('--x=1 --y=2 --z=3')
((), {'y': 2, 'x': 1, 'z': 3})

The Utility Module — clime.util

It contains the helper functions.

clime.util.autotype(s)[source]

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

clime.util.getargspec(func)[source]

Get the argument specification of func.

Parameters:func (a python function, built-in function or bound method) – The target.
Return type:(args, varargs, keywords, defaults)

It gets 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.util.json(s)[source]

Convert a JSON string s into a Python’s type.

Run Clime as a Command

Clime lets you use python -m clime or clime in shell to converts a Python program or Python module temporarily.

Here are some examples:

$ python -m clime math
usage: acos [-x] <x>
   or: acosh [-x] <x>
   or: asin [-x] <x>
   or: asinh [-x] <x>
   or: atan [-x] <x>
...
$ python -m clime math hypot --help
usage: hypot [-x] [-y] <x> <y>

hypot(x, y)

Return the Euclidean distance, sqrt(x*x + y*y).
$ python -m clime math hypot 3 4
5.0