Cliff框架介绍
1 cliff简介
Cliff(CommandLine Interface Formulation Framework)，即命令行接口制定框架。可定义多级命令、输出格式以及其他一些扩展来创建命令行相关项目。Cliff框架中定义的主程序处理参数解析，并调用子命令来完成工作。
Cliff借助Python的优势能够动态的装载代码，允许主程序中用到的子命令分布式的实现，并向用户提供统一的命令行界面，方便开发者组织源码。Neutron提供了命令行模式、交互式模式，正是基于cliff架构实现的。
cliff框架中包括了最基本的四类对象
1 theapplication
Cliff.app.App是cliff框架的主程序，负责参数解析、配置logging、设置I/O流等。
2 theCommandManager
cliff.commandmanager.CommandManager 用于加载子命令，默认是通过setuptools entry points机制实现。
3 theCommand
cliff.command.Command 可通过继承该类实现相应的子命令供主程序调用。
4 theInteractive Application
主程序调用cliff.interactive.InteractiveApp实例向用户提供command-shell模式，用户可输入多个命令。
cliff objects之间的关系
Cliff.app.App类中，初始化函数包括定义self.commandmanager，它是cliff.commandmanager.CommandManager的实例，self.interactive-app-factory,它是cliff.interactive.InteractiveApp的实例。run()函数是主程序入口函数。
输出格式
List命令提供的输出格式：csv, table, value, yaml, json, HTML，使用方法是在命令后面输入：-f 输出格式；Show命令提供的输出格式：table,shell, value, yaml, json, HTML，下面举例介绍各种格式的特点，HTML格式需要安装cliff-tablib，这里不做演示。
Csv格式：
|
(.venv)$ cliffdemo files -f csv "Name","Size" "build",136 "cliffdemo.log",2690 "Makefile",5569 "source",408 |
Table格式：
|
(.venv)$ cliffdemo files +---------------+------+ | Name | Size | +---------------+------+ | build | 136 | | cliffdemo.log | 2546 | | Makefile | 5569 | | source | 408 | +---------------+------+ |
Value格式
|
(.venv)$ cliffdemo files -f value build 136 cliffdemo.log 2690 Makefile 5569 source 408 |
Yaml格式：
|
(.venv)$ cliffdemo files -f yaml - Name: dist Size: 4096 - Name: cliffdemo.egg-info Size: 4096 - Name: README.rst Size: 960 - Name: setup.py Size: 1807 |
Json 格式：
|
(.venv)$ cliffdemo files -f json [ { "Name": "source", "Size": 4096 }, { "Name": "Makefile", "Size": 5569 }, ] |
Shell格式：
|
(.venv)$ cliffdemo file -f shell setup.py name="setup.py" size="5916" uid="527" gid="501" modified_time="1335655655.0" |
OpenStack与cliff的关系
Openstack提供的命令行程序正是基于cliff框架编写。Neutron-client实现了用于调用Neutron APIs 命令行接口。Neutronclient的主程序NeutronShell类继承cliff.app.App类，初始化函数中定义了command-manager，interactive-app。对终端输入的neutron命令进行参数解析、配置logging并调用相关子命令来完成neutron命令操作。输入的命令是由sys.argv[1:]获取。
Neutronclient目录结构：
| neutronclient ---common ---neutron --v2_0 --client.py ---tests ---v2_0 ---client.py ---i18n.py ---shell.py ---version.py |
neutron-client中如何添加CLI命令
通过添加neutronservice-create命令来介绍，当终端输入service-create命令时，要求输出service-create命令所有的参数，且参数可用。
1、注册新的CLI命令
Neutron提供的命令行接口是定义在python-neutronclient/neutronclient/shell.py文件，以字典形式注册在COMMAND_V2中，因此需要在COMMAND_V2中注册新的命令：
| COMMAND_V2 = { 'net-list': network.ListNetwork, … 'service-create': network.CreateService, } |
Service-create具体实现是在network.py文件提供的CreateService类中实现。
2、设置service-create命令提供的参数
这部分设置是在类CreateService中实现。
| import argparse # 调用argparse模块用于参数解析，参数添加，参数行为设置等
from neutronclient.common import exceptions from neutronclient.i18n import _ from neutronclient.neutron import v2_0 as neutronV20 # 该类提供了CreateCommand类
class CreateService(neutronV20.CreateCommand): """Create a service."""
resource = 'service' # neutron client向OpenStack API端对service资源进行操作
def add_known_arguments(self, parser): # 对service-create命令添加参数，并设置参数的行为 parser.add_argument( '--admin-state-down', dest='admin_state', action='store_false', help=_('Set admin state up to false.')) parser.add_argument( '--admin_state_down', dest='admin_state', action='store_false', help=argparse.SUPPRESS) parser.add_argument( 'name', metavar='NAME', help=_('Name of service to create.')) parser.add_argument( '--description', dest='description', help=_('Description of the service')) parser.add_argument( '--shared', dest='share', choices=['True', 'False'], default=argparse.SUPPRESS, help=_('Shared or not')) parser.add_argument( '--test', dest='test', action='store_const', const='value-to-const', help=_('Test for const value')) parser.add_argument( '--ips', dest='ips', nargs=2, default='a', help=_('Add multible arguments')) parser.add_argument( '-r', '--retries', metavar="NUM", dest='r', type=int, default=0, help=_("How many times the request to the Neutron server should " "be retried if it fails."))
def args2body(self, parsed_args): body = {'service': { 'name': parsed_args.name, 'admin_state_up': parsed_args.admin_state, 'ips': parsed_args.ips, 'description':parsed_args.description, 'test': parsed_args.test, 'shared': parsed_args.share, 'r': parsed_args.r}, } neutronV20.update_dict(parsed_args, body['service'], ['shared', 'tenant_id']) return body |
代码中向service-create命令添加了如下参数：
1 --admin-state-down/--admin_state_down，其action：store-false，表示其默认值为false，输入为true。
2 name，前面没有添加‘—’表示为必选参数，输入service-create命令时必须输入name。
3 --description，没有添加action，但默认action是type=str，表示该值是字符串形式。
4 --shared，带有choice选项，表示该值只可是choice中的一个值。
5 --test，action值为‘store-const’，表示test值在const中指定。
6 --ips，action值为‘nargs=2’，表示ips可选参数后面需加两个值。
7 -r,参数--retries，是-r参数的别名，区别是前面的短横线个数不同。其中type=int，表示其输入值是整形数值。
3、显示新添加的命令其参数值
根据neutron-client中代码执行走向，在CreateService类的父类CreateCommand中定义的get-data()函数中输出命令的返回结果。
| class CreateCommand(NeutronCommand, show.ShowOne): """Create a resource for a given tenant."" def get_parser(self, prog_name): … … def get_data(self, parsed_args): self.log.debug('get_data(%s)' % parsed_args) _extra_values = parse_args_to_dict(self.values_specs) _merge_args(self, parsed_args, _extra_values, self.values_specs) body = self.args2body(parsed_args) # body中返回所创建的service下所有的参数及对应的值 print("_extra_values") print(_extra_values) print("body:") print(body) return neutron_client = self.get_client() # 设置neutron-client，调用OpenStack APIs neutron_client.format = parsed_args.request_format … … |
执行service-createabc --retries 2 - -shared True ，或者执行service-create abc -r 2 - -shared True，返回结果相同。
| service-create abc --retries 2 --shared True _extra_values {} body: {'service': {'description': None, 'admin_state_up': True, 'ips': 'a, b', 'r': 2, 'test': None, 'shared': 'True', 'name': 'abc'}} |
参考资料
Cliff文档：http://docs.openstack.org/developer/cliff/
Cliff源码：https://github.com/dreamhost/cliff
Argparse模块：http://www.2cto.com/kf/201208/149418.html
http://blog.itpub.net/26250550/viewspace-1281968/
http://blog.chinaunix.net/xmlrpc.php?r=blog/article&uid=21633169&id=4387657