~justin-fathomdb/nova/justinsb-openstack-api-volumes

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Parsing command-lines with usage.Options</title>

</head>

<h1 class="title">Parsing command-lines with usage.Options</h1>

<div class="toc"><ol><li><a href="#auto0">Introduction</a></li><li><a href="#auto1">Boolean Options</a></li><ul><li><a href="#auto2">Inheritance, Or: How I Learned to Stop Worrying and Love

the Superclass</a></li></ul><li><a href="#auto3">Parameters</a></li><li><a href="#auto4">Option Subcommands</a></li><li><a href="#auto5">Generic Code For Options</a></li><li><a href="#auto6">Parsing Arguments</a></li><li><a href="#auto7">Post Processing</a></li><li><a href="#auto8">Type enforcement</a></li></ol></div>

<h2>Introduction<a name="auto0"/></h2>

There is frequently a need for programs to parse a UNIX-like

command line program: options preceded by <code>-</code> or

<code>--</code>, sometimes followed by a parameter, followed by

a list of arguments. The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.usage.html" title="twisted.python.usage">twisted.python.usage</a></code> provides a class,

<code>Options</code>, to facilitate such parsing.

While Python has the <code>getopt</code> module for doing

this, it provides a very low level of abstraction for options.

Twisted has a higher level of abstraction, in the class <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.usage.Options.html" title="twisted.python.usage.Options">twisted.python.usage.Options</a></code>. It uses

Python's reflection facilities to provide an easy to use yet

flexible interface to the command line. While most command line

processors either force the application writer to write her own

loops, or have arbitrary limitations on the command line (the

most common one being not being able to have more then one

instance of a specific option, thus rendering the idiom

<code class="shell">program -v -v -v</code> impossible), Twisted allows the

programmer to decide how much control she wants.

The <code>Options</code> class is used by subclassing. Since

a lot of time it will be used in the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.tap.html" title="twisted.tap">twisted.tap</a></code> package, where the local

conventions require the specific options parsing class to also

be called <code>Options</code>, it is usually imported with

<pre class="python">1

from twisted.python import usage

</pre>

<h2>Boolean Options<a name="auto1"/></h2>

For simple boolean options, define the attribute

<code>optFlags</code> like this:

<pre class="python">1

class Options(usage.Options):

optFlags = [["fast", "f", "Act quickly"], ["safe", "s", "Act safely"]]

</pre>

<code>optFlags</code> should be a list of 3-lists. The first element

is the long name, and will be used on the command line as

<code>--fast</code>. The second one is the short name, and will be used

on the command line as <code>-f</code>. The last element is a

description of the flag and will be used to generate the usage

information text. The long name also determines the name of the key

that will be set on the Options instance. Its value will be 1 if the

option was seen, 0 otherwise. Here is an example for usage:

<pre class="python"> 1

class Options(usage.Options):

optFlags = [

["fast", "f", "Act quickly"],

["good", "g", "Act well"],

["cheap", "c", "Act cheaply"]

]

command_line = ["-g", "--fast"]

options = Options()

try:

options.parseOptions(command_line)

except usage.UsageError, errortext:

print '%s: %s' % (sys.argv[0], errortext)

100

print '%s: Try --help for usage details.' % (sys.argv[0])

101

sys.exit(1)

102

if options['fast']:

103

print "fast",

104

if options['good']:

105

print "good",

106

if options['cheap']:

107

print "cheap",

108

print

109

</pre>

110

111

The above will print <code>fast good</code>.

112

113

Note here that Options fully supports the mapping interface. You can

114

access it mostly just like you can access any other dict. Options are stored

115

as mapping items in the Options instance: parameters as 'paramname': 'value'

116

and flags as 'flagname': 1 or 0.

117

118

<h3>Inheritance, Or: How I Learned to Stop Worrying and Love

119

the Superclass<a name="auto2"/></h3>

120

121

Sometimes there is a need for several option processors with

122

a unifying core. Perhaps you want all your commands to

123

understand <code>-q</code>/<code>--quiet</code> means to be

124

quiet, or something similar. On the face of it, this looks

125

impossible: in Python, the subclass's <code>optFlags</code>

126

would shadow the superclass's. However,

127

<code>usage.Options</code> uses special reflection code to get

128

all of the <code>optFlags</code> defined in the hierarchy. So

129

the following:

130

<pre class="python">1

131

132

133

134

135

136

137

138

139

class BaseOptions(usage.Options):

140

141

optFlags = [["quiet", "q", None]]

142

143

class SpecificOptions(BaseOptions):

144

145

optFlags = [

146

["fast", "f", None], ["good", "g", None], ["cheap", "c", None]

147

]

148

</pre>

149

Is the same as:

150

<pre class="python">1

151

152

153

154

155

156

157

158

class SpecificOptions(BaseOptions):

159

160

optFlags = [

161

["quiet", "q", "Silence output"],

162

["fast", "f", "Run quickly"],

163

["good", "g", "Don't validate input"],

164

["cheap", "c", "Use cheap resources"]

165

]

166

</pre>

167

168

<h2>Parameters<a name="auto3"/></h2>

169

170

Parameters are specified using the attribute

171

<code>optParameters</code>. They must be given a

172

default. If you want to make sure you got the parameter from

173

the command line, give a non-string default. Since the command

174

line only has strings, this is completely reliable.

175

176

Here is an example:

177

<pre class="python"> 1

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

class Options(usage.Options):

210

211

optFlags = [

212

["fast", "f", "Run quickly"],

213

["good", "g", "Don't validate input"],

214

["cheap", "c", "Use cheap resources"]

215

]

216

optParameters = [["user", "u", None, "The user name"]]

217

218

config = Options()

219

try:

220

config.parseOptions() # When given no argument, parses sys.argv[1:]

221

except usage.UsageError, errortext:

222

223

224

sys.exit(1)

225

226

if config['user'] is not None:

227

print "Hello", config['user']

228

print "So, you want it:"

229

230

if config['fast']:

231

print "fast",

232

if config['good']:

233

print "good",

234

if config['cheap']:

235

print "cheap",

236

print

237

</pre>

238

239

Like <code>optFlags</code>, <code>optParameters</code> works

240

smoothly with inheritance.

241

242

<h2>Option Subcommands<a name="auto4"/></h2>

243

244

It is useful, on occassion, to group a set of options together based

245

on the logical <q>action</q> to which they belong. For this, the

246

<code>usage.Options</code> class allows you to define a set of

247

<q>subcommands</q>, each of which can provide its own

248

<code>usage.Options</code> instance to handle its particular

249

options.

250

251

Here is an example for an Options class that might parse

252

options like those the cvs program takes

253

<pre class="python"> 1

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

class ImportOptions(usage.Options):

281

optParameters = [

282

['module', 'm', None, None], ['vendor', 'v', None, None],

283

['release', 'r', None]

284

]

285

286

class CheckoutOptions(usage.Options):

287

optParameters = [['module', 'm', None, None], ['tag', 'r', None, None]]

288

289

class Options(usage.Options):

290

subCommands = [['import', None, ImportOptions, "Do an Import"],

291

['checkout', None, CheckoutOptions, "Do a Checkout"]]

292

293

optParameters = [

294

['compression', 'z', 0, 'Use compression'],

295

['repository', 'r', None, 'Specify an alternate repository']

296

]

297

298

config = Options(); config.parseOptions()

299

if config.subCommand == 'import':

300

doImport(config.subOptions)

301

elif config.subCommand == 'checkout':

302

doCheckout(config.subOptions)

303

</pre>

304

305

The <code>subCommands</code> attribute of <code>Options</code>

306

directs the parser to the two other <code>Options</code> subclasses

307

when the strings <code>"import"</code> or <code>"checkout"</code> are

308

present on the command

309

line. All options after the given command string are passed to the

310

specified Options subclass for further parsing. Only one subcommand

311

may be specified at a time. After parsing has completed, the Options

312

instance has two new attributes - <code>subCommand</code> and <code>

313

subOptions</code> - which hold the command string and the Options

314

instance used to parse the remaining options.

315

316

<h2>Generic Code For Options<a name="auto5"/></h2>

317

318

Sometimes, just setting an attribute on the basis of the

319

options is not flexible enough. In those cases, Twisted does

320

not even attempt to provide abstractions such as <q>counts</q> or

321

<q>lists</q>, but rathers lets you call your own method, which will

322

be called whenever the option is encountered.

323

324

Here is an example of counting verbosity

325

<pre class="python"> 1

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

class Options(usage.Options):

344

345

def __init__(self):

346

usage.Options.__init__(self)

347

self['verbosity'] = 0 # default

348

349

def opt_verbose(self):

350

self['verbosity'] = self['verbosity']+1

351

352

def opt_quiet(self):

353

354

355

opt_v = opt_verbose

356

opt_q = opt_quiet

357

</pre>

358

359

Command lines that look like

360

<code class="shell">command -v -v -v -v</code> will

361

increase verbosity to 4, while

362

<code class="shell">command -q -q -q</code> will decrease

363

verbosity to -3.

364

365

366

The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.usage.Options.html" title="twisted.python.usage.Options">usage.Options</a></code>

367

class knows that these are

368

parameter-less options, since the methods do not receive an

369

argument. Here is an example for a method with a parameter:

370

371

<pre class="python"> 1

372

373

374

375

376

377

378

379

380

381

382

383

384

385

class Options(usage.Options):

386

387

def __init__(self):

388

usage.Options.__init__(self)

389

self['symbols'] = []

390

391

def opt_define(self, symbol):

392

self['symbols'].append(symbol)

393

394

opt_D = opt_define

395

</pre>

396

397

This example is useful for the common idiom of having

398

<code>command -DFOO -DBAR</code> to define symbols.

399

400

<h2>Parsing Arguments<a name="auto6"/></h2>

401

402

<code>usage.Options</code> does not stop helping when the

403

last parameter is gone. All the other arguments are sent into a

404

function which should deal with them. Here is an example for a

405

<code>cmp</code> like command.

406

<pre class="python">1

407

408

409

410

411

412

413

414

415

416

417

class Options(usage.Options):

418

419

optParameters = [["max_differences", "d", 1, None]]

420

421

def parseArgs(self, origin, changed):

422

self['origin'] = origin

423

self['changed'] = changed

424

</pre>

425

426

The command should look like <code>command origin

427

changed</code>.

428

429

If you want to have a variable number of left-over

430

arguments, just use <code>def parseArgs(self, *args):</code>.

431

This is useful for commands like the UNIX

432

<code>cat(1)</code>.

433

434

<h2>Post Processing<a name="auto7"/></h2>

435

436

Sometimes, you want to perform post processing of options to

437

patch up inconsistencies, and the like. Here is an example:

438

<pre class="python"> 1

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

class Options(usage.Options):

454

455

optFlags = [

456

["fast", "f", "Run quickly"],

457

["good", "g", "Don't validate input"],

458

["cheap", "c", "Use cheap resources"]

459

]

460

461

def postOptions(self):

462

if self['fast'] and self['good'] and self['cheap']:

463

raise usage.UsageError, "can't have it all, brother"

464

</pre>

465

466

<h2>Type enforcement<a name="auto8"/></h2>

467

468

By default, all options are handled as strings. You may want to

469

enforce the type of your option in some specific case, the classic example

470

being port number. Any callable can be specified in the fifth row of

471

<code>optParameters</code> and will be called with the string value passed

472

in parameter.

473

474

475

<pre class="python">1

476

477

478

479

480

481

482

class Options(usage.Options):

483

optParameters = [["shiny_integer", "s", 1, None, int]]

484

optParameters = [["dummy_float", "d", 3.14159, None, float]]

485

</pre>

486

487

Note that default values are not coerced, so you should either declare

488

it with the good type (as above) or handle it when you use your

489

options.

490

491

The coerce function may have a coerceDoc attribute, the content of which

492

will be printed after the documentation of the option. It's particularly

493

useful for reusing the function at multiple places.

494

495

<pre class="python"> 1

496

497

498

499

500

501

502

503

504

505

506

def oneTwoThree(val):

507

val = int(val)

508

if val not in range(1, 4):

509

raise ValueError("Not in range")

510

return val

511

oneTwoThree.coerceDoc = "Must be 1, 2 or 3."

512

513

from twisted.python import usage

514

515

class Options(usage.Options):

516

optParameters = [["one_choice", "o", 1, None, oneTwoThree]]

517

</pre>

518

519

This example code will print the following help when added to your program:

520

521

522

523

$ python myprogram.py --help

524

Usage: myprogram [options]

525

Options:

526

-o, --one_choice= [default: 0]. Must be 1, 2 or 3.

527

</pre>

528

</div>

529

530

<a href="index.html">Index</a>

531

Version: 10.0.0

532

</body>

533

</html>

b'\\ No newline at end of file'

Older »