doc/core/howto/options.html

   1 <?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">
   2   <head>
   3 <title>Twisted Documentation: Parsing command-lines with usage.Options</title>
   4 <link href="stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Parsing command-lines with usage.Options</h1>
   9     <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
  10     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><li><a href="#auto9">Shell tab-completion</a></li><ul><li><a href="#auto10">Completion metadata</a></li></ul></ol></div>
  11     <div class="content">
  12     <span/>
  13
  14     <h2>Introduction<a name="auto0"/></h2>
  15
  16     <p>There is frequently a need for programs to parse a UNIX-like
  17     command line program: options preceded by <code>-</code> or
  18     <code>--</code>, sometimes followed by a parameter, followed by
  19     a list of arguments. The <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.python.usage.html" title="twisted.python.usage">twisted.python.usage</a></code> provides a class,
  20     <code>Options</code>, to facilitate such parsing.</p>
  21
  22     <p>While Python has the <code>getopt</code> module for doing
  23     this, it provides a very low level of abstraction for options.
  24     Twisted has a higher level of abstraction, in the class <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.python.usage.Options.html" title="twisted.python.usage.Options">twisted.python.usage.Options</a></code>. It uses
  25     Python's reflection facilities to provide an easy to use yet
  26     flexible interface to the command line. While most command line
  27     processors either force the application writer to write her own
  28     loops, or have arbitrary limitations on the command line (the
  29     most common one being not being able to have more then one
  30     instance of a specific option, thus rendering the idiom
  31     <code class="shell">program -v -v -v</code> impossible), Twisted allows the
  32     programmer to decide how much control she wants.</p>
  33
  34     <p>The <code>Options</code> class is used by subclassing. Since
  35     a lot of time it will be used in the <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.tap.html" title="twisted.tap">twisted.tap</a></code> package, where the local
  36     conventions require the specific options parsing class to also
  37     be called <code>Options</code>, it is usually imported with</p>
  38 <pre class="python"><p class="py-linenumber">1
  39 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
  40 </pre>
  41
  42     <h2>Boolean Options<a name="auto1"/></h2>
  43
  44     <p>For simple boolean options, define the attribute
  45     <code>optFlags</code> like this:</p>
  46 <pre class="python"><p class="py-linenumber">1
  47 2
  48 3
  49 </p><span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
  50
  51     <span class="py-src-variable">optFlags</span> = [[<span class="py-src-string">&quot;fast&quot;</span>, <span class="py-src-string">&quot;f&quot;</span>, <span class="py-src-string">&quot;Act quickly&quot;</span>], [<span class="py-src-string">&quot;safe&quot;</span>, <span class="py-src-string">&quot;s&quot;</span>, <span class="py-src-string">&quot;Act safely&quot;</span>]]
  52 </pre>
  53     <p><code>optFlags</code> should be a list of 3-lists. The first element
  54     is the long name, and will be used on the command line as
  55     <code>--fast</code>. The second one is the short name, and will be used
  56     on the command line as <code>-f</code>. The last element is a
  57     description of the flag and will be used to generate the usage
  58     information text.  The long name also determines the name of the key
  59     that will be set on the Options instance. Its value will be 1 if the
  60     option was seen, 0 otherwise. Here is an example for usage:</p>
  61 <pre class="python"><p class="py-linenumber"> 1
  62  2
  63  3
  64  4
  65  5
  66  6
  67  7
  68  8
  69  9
  70 10
  71 11
  72 12
  73 13
  74 14
  75 15
  76 16
  77 17
  78 18
  79 19
  80 20
  81 21
  82 22
  83 23
  84 24
  85 </p><span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
  86
  87     <span class="py-src-variable">optFlags</span> = [
  88         [<span class="py-src-string">&quot;fast&quot;</span>, <span class="py-src-string">&quot;f&quot;</span>, <span class="py-src-string">&quot;Act quickly&quot;</span>],
  89         [<span class="py-src-string">&quot;good&quot;</span>, <span class="py-src-string">&quot;g&quot;</span>, <span class="py-src-string">&quot;Act well&quot;</span>],
  90         [<span class="py-src-string">&quot;cheap&quot;</span>, <span class="py-src-string">&quot;c&quot;</span>, <span class="py-src-string">&quot;Act cheaply&quot;</span>]
  91     ]
  92
  93 <span class="py-src-variable">command_line</span> = [<span class="py-src-string">&quot;-g&quot;</span>, <span class="py-src-string">&quot;--fast&quot;</span>]
  94
  95 <span class="py-src-variable">options</span> = <span class="py-src-variable">Options</span>()
  96 <span class="py-src-keyword">try</span>:
  97     <span class="py-src-variable">options</span>.<span class="py-src-variable">parseOptions</span>(<span class="py-src-variable">command_line</span>)
  98 <span class="py-src-keyword">except</span> <span class="py-src-variable">usage</span>.<span class="py-src-variable">UsageError</span>, <span class="py-src-variable">errortext</span>:
  99     <span class="py-src-keyword">print</span> <span class="py-src-string">'%s: %s'</span> % (<span class="py-src-variable">sys</span>.<span class="py-src-variable">argv</span>[<span class="py-src-number">0</span>], <span class="py-src-variable">errortext</span>)
 100     <span class="py-src-keyword">print</span> <span class="py-src-string">'%s: Try --help for usage details.'</span> % (<span class="py-src-variable">sys</span>.<span class="py-src-variable">argv</span>[<span class="py-src-number">0</span>])
 101     <span class="py-src-variable">sys</span>.<span class="py-src-variable">exit</span>(<span class="py-src-number">1</span>)
 102 <span class="py-src-keyword">if</span> <span class="py-src-variable">options</span>[<span class="py-src-string">'fast'</span>]:
 103     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;fast&quot;</span>,
 104 <span class="py-src-keyword">if</span> <span class="py-src-variable">options</span>[<span class="py-src-string">'good'</span>]:
 105     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;good&quot;</span>,
 106 <span class="py-src-keyword">if</span> <span class="py-src-variable">options</span>[<span class="py-src-string">'cheap'</span>]:
 107     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;cheap&quot;</span>,
 108 <span class="py-src-keyword">print</span>
 109 </pre>
 110
 111     <p>The above will print <code>fast good</code>.</p>
 112
 113     <p>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.</p>
 117
 118     <h3>Inheritance, Or: How I Learned to Stop Worrying and Love
 119     the Superclass<a name="auto2"/></h3>
 120
 121     <p>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:</p>
 130 <pre class="python"><p class="py-linenumber">1
 131 2
 132 3
 133 4
 134 5
 135 6
 136 7
 137 8
 138 9
 139 </p><span class="py-src-keyword">class</span> <span class="py-src-identifier">BaseOptions</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 140
 141     <span class="py-src-variable">optFlags</span> = [[<span class="py-src-string">&quot;quiet&quot;</span>, <span class="py-src-string">&quot;q&quot;</span>, <span class="py-src-variable">None</span>]]
 142
 143 <span class="py-src-keyword">class</span> <span class="py-src-identifier">SpecificOptions</span>(<span class="py-src-parameter">BaseOptions</span>):
 144
 145     <span class="py-src-variable">optFlags</span> = [
 146         [<span class="py-src-string">&quot;fast&quot;</span>, <span class="py-src-string">&quot;f&quot;</span>, <span class="py-src-variable">None</span>], [<span class="py-src-string">&quot;good&quot;</span>, <span class="py-src-string">&quot;g&quot;</span>, <span class="py-src-variable">None</span>], [<span class="py-src-string">&quot;cheap&quot;</span>, <span class="py-src-string">&quot;c&quot;</span>, <span class="py-src-variable">None</span>]
 147     ]
 148 </pre>
 149     <p>Is the same as: </p>
 150 <pre class="python"><p class="py-linenumber">1
 151 2
 152 3
 153 4
 154 5
 155 6
 156 7
 157 8
 158 </p><span class="py-src-keyword">class</span> <span class="py-src-identifier">SpecificOptions</span>(<span class="py-src-parameter">BaseOptions</span>):
 159
 160     <span class="py-src-variable">optFlags</span> = [
 161         [<span class="py-src-string">&quot;quiet&quot;</span>, <span class="py-src-string">&quot;q&quot;</span>, <span class="py-src-string">&quot;Silence output&quot;</span>],
 162         [<span class="py-src-string">&quot;fast&quot;</span>, <span class="py-src-string">&quot;f&quot;</span>, <span class="py-src-string">&quot;Run quickly&quot;</span>],
 163         [<span class="py-src-string">&quot;good&quot;</span>, <span class="py-src-string">&quot;g&quot;</span>, <span class="py-src-string">&quot;Don't validate input&quot;</span>],
 164         [<span class="py-src-string">&quot;cheap&quot;</span>, <span class="py-src-string">&quot;c&quot;</span>, <span class="py-src-string">&quot;Use cheap resources&quot;</span>]
 165     ]
 166 </pre>
 167
 168     <h2>Parameters<a name="auto3"/></h2>
 169
 170     <p>Parameters are specified using the attribute
 171     <code>optParameters</code>. They <em>must</em> 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.</p>
 175
 176     <p>Here is an example:</p>
 177 <pre class="python"><p class="py-linenumber"> 1
 178  2
 179  3
 180  4
 181  5
 182  6
 183  7
 184  8
 185  9
 186 10
 187 11
 188 12
 189 13
 190 14
 191 15
 192 16
 193 17
 194 18
 195 19
 196 20
 197 21
 198 22
 199 23
 200 24
 201 25
 202 26
 203 27
 204 28
 205 29
 206 30
 207 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 208
 209 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 210
 211     <span class="py-src-variable">optFlags</span> = [
 212         [<span class="py-src-string">&quot;fast&quot;</span>, <span class="py-src-string">&quot;f&quot;</span>, <span class="py-src-string">&quot;Run quickly&quot;</span>],
 213         [<span class="py-src-string">&quot;good&quot;</span>, <span class="py-src-string">&quot;g&quot;</span>, <span class="py-src-string">&quot;Don't validate input&quot;</span>],
 214         [<span class="py-src-string">&quot;cheap&quot;</span>, <span class="py-src-string">&quot;c&quot;</span>, <span class="py-src-string">&quot;Use cheap resources&quot;</span>]
 215     ]
 216     <span class="py-src-variable">optParameters</span> = [[<span class="py-src-string">&quot;user&quot;</span>, <span class="py-src-string">&quot;u&quot;</span>, <span class="py-src-variable">None</span>, <span class="py-src-string">&quot;The user name&quot;</span>]]
 217
 218 <span class="py-src-variable">config</span> = <span class="py-src-variable">Options</span>()
 219 <span class="py-src-keyword">try</span>:
 220     <span class="py-src-variable">config</span>.<span class="py-src-variable">parseOptions</span>() <span class="py-src-comment"># When given no argument, parses sys.argv[1:]</span>
 221 <span class="py-src-keyword">except</span> <span class="py-src-variable">usage</span>.<span class="py-src-variable">UsageError</span>, <span class="py-src-variable">errortext</span>:
 222     <span class="py-src-keyword">print</span> <span class="py-src-string">'%s: %s'</span> % (<span class="py-src-variable">sys</span>.<span class="py-src-variable">argv</span>[<span class="py-src-number">0</span>], <span class="py-src-variable">errortext</span>)
 223     <span class="py-src-keyword">print</span> <span class="py-src-string">'%s: Try --help for usage details.'</span> % (<span class="py-src-variable">sys</span>.<span class="py-src-variable">argv</span>[<span class="py-src-number">0</span>])
 224     <span class="py-src-variable">sys</span>.<span class="py-src-variable">exit</span>(<span class="py-src-number">1</span>)
 225
 226 <span class="py-src-keyword">if</span> <span class="py-src-variable">config</span>[<span class="py-src-string">'user'</span>] <span class="py-src-keyword">is</span> <span class="py-src-keyword">not</span> <span class="py-src-variable">None</span>:
 227     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;Hello&quot;</span>, <span class="py-src-variable">config</span>[<span class="py-src-string">'user'</span>]
 228 <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;So, you want it:&quot;</span>
 229
 230 <span class="py-src-keyword">if</span> <span class="py-src-variable">config</span>[<span class="py-src-string">'fast'</span>]:
 231     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;fast&quot;</span>,
 232 <span class="py-src-keyword">if</span> <span class="py-src-variable">config</span>[<span class="py-src-string">'good'</span>]:
 233     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;good&quot;</span>,
 234 <span class="py-src-keyword">if</span> <span class="py-src-variable">config</span>[<span class="py-src-string">'cheap'</span>]:
 235     <span class="py-src-keyword">print</span> <span class="py-src-string">&quot;cheap&quot;</span>,
 236 <span class="py-src-keyword">print</span>
 237 </pre>
 238
 239     <p>Like <code>optFlags</code>, <code>optParameters</code> works
 240     smoothly with inheritance.</p>
 241
 242     <h2>Option Subcommands<a name="auto4"/></h2>
 243
 244     <p>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.</p>
 250
 251     <p>Here is an example for an Options class that might parse
 252     options like those the cvs program takes</p>
 253 <pre class="python"><p class="py-linenumber"> 1
 254  2
 255  3
 256  4
 257  5
 258  6
 259  7
 260  8
 261  9
 262 10
 263 11
 264 12
 265 13
 266 14
 267 15
 268 16
 269 17
 270 18
 271 19
 272 20
 273 21
 274 22
 275 23
 276 24
 277 25
 278 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 279
 280 <span class="py-src-keyword">class</span> <span class="py-src-identifier">ImportOptions</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 281     <span class="py-src-variable">optParameters</span> = [
 282         [<span class="py-src-string">'module'</span>, <span class="py-src-string">'m'</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">None</span>], [<span class="py-src-string">'vendor'</span>, <span class="py-src-string">'v'</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">None</span>],
 283         [<span class="py-src-string">'release'</span>, <span class="py-src-string">'r'</span>, <span class="py-src-variable">None</span>]
 284     ]
 285
 286 <span class="py-src-keyword">class</span> <span class="py-src-identifier">CheckoutOptions</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 287     <span class="py-src-variable">optParameters</span> = [[<span class="py-src-string">'module'</span>, <span class="py-src-string">'m'</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">None</span>], [<span class="py-src-string">'tag'</span>, <span class="py-src-string">'r'</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">None</span>]]
 288
 289 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 290     <span class="py-src-variable">subCommands</span> = [[<span class="py-src-string">'import'</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">ImportOptions</span>, <span class="py-src-string">&quot;Do an Import&quot;</span>],
 291                    [<span class="py-src-string">'checkout'</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">CheckoutOptions</span>, <span class="py-src-string">&quot;Do a Checkout&quot;</span>]]
 292
 293     <span class="py-src-variable">optParameters</span> = [
 294         [<span class="py-src-string">'compression'</span>, <span class="py-src-string">'z'</span>, <span class="py-src-number">0</span>, <span class="py-src-string">'Use compression'</span>],
 295         [<span class="py-src-string">'repository'</span>, <span class="py-src-string">'r'</span>, <span class="py-src-variable">None</span>, <span class="py-src-string">'Specify an alternate repository'</span>]
 296     ]
 297
 298 <span class="py-src-variable">config</span> = <span class="py-src-variable">Options</span>(); <span class="py-src-variable">config</span>.<span class="py-src-variable">parseOptions</span>()
 299 <span class="py-src-keyword">if</span> <span class="py-src-variable">config</span>.<span class="py-src-variable">subCommand</span> == <span class="py-src-string">'import'</span>:
 300     <span class="py-src-variable">doImport</span>(<span class="py-src-variable">config</span>.<span class="py-src-variable">subOptions</span>)
 301 <span class="py-src-keyword">elif</span> <span class="py-src-variable">config</span>.<span class="py-src-variable">subCommand</span> == <span class="py-src-string">'checkout'</span>:
 302     <span class="py-src-variable">doCheckout</span>(<span class="py-src-variable">config</span>.<span class="py-src-variable">subOptions</span>)
 303 </pre>
 304
 305     <p>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>&quot;import&quot;</code> or <code>&quot;checkout&quot;</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.</p>
 315
 316     <h2>Generic Code For Options<a name="auto5"/></h2>
 317
 318     <p>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.</p>
 323
 324     <p>Here is an example of counting verbosity</p>
 325 <pre class="python"><p class="py-linenumber"> 1
 326  2
 327  3
 328  4
 329  5
 330  6
 331  7
 332  8
 333  9
 334 10
 335 11
 336 12
 337 13
 338 14
 339 15
 340 16
 341 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 342
 343 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 344
 345     <span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>):
 346         <span class="py-src-variable">usage</span>.<span class="py-src-variable">Options</span>.<span class="py-src-variable">__init__</span>(<span class="py-src-variable">self</span>)
 347         <span class="py-src-variable">self</span>[<span class="py-src-string">'verbosity'</span>] = <span class="py-src-number">0</span> <span class="py-src-comment"># default</span>
 348
 349     <span class="py-src-keyword">def</span> <span class="py-src-identifier">opt_verbose</span>(<span class="py-src-parameter">self</span>):
 350         <span class="py-src-variable">self</span>[<span class="py-src-string">'verbosity'</span>] = <span class="py-src-variable">self</span>[<span class="py-src-string">'verbosity'</span>]+<span class="py-src-number">1</span>
 351
 352     <span class="py-src-keyword">def</span> <span class="py-src-identifier">opt_quiet</span>(<span class="py-src-parameter">self</span>):
 353         <span class="py-src-variable">self</span>[<span class="py-src-string">'verbosity'</span>] = <span class="py-src-variable">self</span>[<span class="py-src-string">'verbosity'</span>]-<span class="py-src-number">1</span>
 354
 355     <span class="py-src-variable">opt_v</span> = <span class="py-src-variable">opt_verbose</span>
 356     <span class="py-src-variable">opt_q</span> = <span class="py-src-variable">opt_quiet</span>
 357 </pre>
 358
 359     <p>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     </p>
 365
 366     <p>The <code class="API"><a href="http://twistedmatrix.com/documents/12.1.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:</p>
 370
 371 <pre class="python"><p class="py-linenumber"> 1
 372  2
 373  3
 374  4
 375  5
 376  6
 377  7
 378  8
 379  9
 380 10
 381 11
 382 12
 383 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 384
 385 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 386
 387     <span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>):
 388         <span class="py-src-variable">usage</span>.<span class="py-src-variable">Options</span>.<span class="py-src-variable">__init__</span>(<span class="py-src-variable">self</span>)
 389         <span class="py-src-variable">self</span>[<span class="py-src-string">'symbols'</span>] = []
 390
 391     <span class="py-src-keyword">def</span> <span class="py-src-identifier">opt_define</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">symbol</span>):
 392         <span class="py-src-variable">self</span>[<span class="py-src-string">'symbols'</span>].<span class="py-src-variable">append</span>(<span class="py-src-variable">symbol</span>)
 393
 394     <span class="py-src-variable">opt_D</span> = <span class="py-src-variable">opt_define</span>
 395 </pre>
 396
 397     <p>This example is useful for the common idiom of having
 398     <code>command -DFOO -DBAR</code> to define symbols.</p>
 399
 400     <h2>Parsing Arguments<a name="auto6"/></h2>
 401
 402     <p><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.</p>
 406 <pre class="python"><p class="py-linenumber">1
 407 2
 408 3
 409 4
 410 5
 411 6
 412 7
 413 8
 414 9
 415 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 416
 417 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 418
 419     <span class="py-src-variable">optParameters</span> = [[<span class="py-src-string">&quot;max_differences&quot;</span>, <span class="py-src-string">&quot;d&quot;</span>, <span class="py-src-number">1</span>, <span class="py-src-variable">None</span>]]
 420
 421     <span class="py-src-keyword">def</span> <span class="py-src-identifier">parseArgs</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">origin</span>, <span class="py-src-parameter">changed</span>):
 422         <span class="py-src-variable">self</span>[<span class="py-src-string">'origin'</span>] = <span class="py-src-variable">origin</span>
 423         <span class="py-src-variable">self</span>[<span class="py-src-string">'changed'</span>] = <span class="py-src-variable">changed</span>
 424 </pre>
 425
 426     <p>The command should look like <code>command origin
 427     changed</code>.</p>
 428
 429     <p>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>.</p>
 433
 434     <h2>Post Processing<a name="auto7"/></h2>
 435
 436     <p>Sometimes, you want to perform post processing of options to
 437     patch up inconsistencies, and the like. Here is an example:</p>
 438 <pre class="python"><p class="py-linenumber"> 1
 439  2
 440  3
 441  4
 442  5
 443  6
 444  7
 445  8
 446  9
 447 10
 448 11
 449 12
 450 13
 451 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 452
 453 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 454
 455     <span class="py-src-variable">optFlags</span> = [
 456         [<span class="py-src-string">&quot;fast&quot;</span>, <span class="py-src-string">&quot;f&quot;</span>, <span class="py-src-string">&quot;Run quickly&quot;</span>],
 457         [<span class="py-src-string">&quot;good&quot;</span>, <span class="py-src-string">&quot;g&quot;</span>, <span class="py-src-string">&quot;Don't validate input&quot;</span>],
 458         [<span class="py-src-string">&quot;cheap&quot;</span>, <span class="py-src-string">&quot;c&quot;</span>, <span class="py-src-string">&quot;Use cheap resources&quot;</span>]
 459     ]
 460
 461     <span class="py-src-keyword">def</span> <span class="py-src-identifier">postOptions</span>(<span class="py-src-parameter">self</span>):
 462         <span class="py-src-keyword">if</span> <span class="py-src-variable">self</span>[<span class="py-src-string">'fast'</span>] <span class="py-src-keyword">and</span> <span class="py-src-variable">self</span>[<span class="py-src-string">'good'</span>] <span class="py-src-keyword">and</span> <span class="py-src-variable">self</span>[<span class="py-src-string">'cheap'</span>]:
 463             <span class="py-src-keyword">raise</span> <span class="py-src-variable">usage</span>.<span class="py-src-variable">UsageError</span>, <span class="py-src-string">&quot;can't have it all, brother&quot;</span>
 464 </pre>
 465
 466     <h2>Type enforcement<a name="auto8"/></h2>
 467
 468     <p>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     </p>
 474
 475 <pre class="python"><p class="py-linenumber">1
 476 2
 477 3
 478 4
 479 5
 480 6
 481 7
 482 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 483
 484 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 485     <span class="py-src-variable">optParameters</span> = [
 486             [<span class="py-src-string">&quot;shiny_integer&quot;</span>, <span class="py-src-string">&quot;s&quot;</span>, <span class="py-src-number">1</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">int</span>],
 487             [<span class="py-src-string">&quot;dummy_float&quot;</span>, <span class="py-src-string">&quot;d&quot;</span>, <span class="py-src-number">3.14159</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">float</span>],
 488         ]
 489 </pre>
 490
 491     <p>Note that default values are not coerced, so you should either declare
 492     it with the good type (as above) or handle it when you use your
 493     options.</p>
 494
 495     <p>The coerce function may have a coerceDoc attribute, the content of which
 496     will be printed after the documentation of the option. It's particularly
 497     useful for reusing the function at multiple places.</p>
 498
 499 <pre class="python"><p class="py-linenumber"> 1
 500  2
 501  3
 502  4
 503  5
 504  6
 505  7
 506  8
 507  9
 508 10
 509 11
 510 </p><span class="py-src-keyword">def</span> <span class="py-src-identifier">oneTwoThree</span>(<span class="py-src-parameter">val</span>):
 511     <span class="py-src-variable">val</span> = <span class="py-src-variable">int</span>(<span class="py-src-variable">val</span>)
 512     <span class="py-src-keyword">if</span> <span class="py-src-variable">val</span> <span class="py-src-keyword">not</span> <span class="py-src-keyword">in</span> <span class="py-src-variable">range</span>(<span class="py-src-number">1</span>, <span class="py-src-number">4</span>):
 513         <span class="py-src-keyword">raise</span> <span class="py-src-variable">ValueError</span>(<span class="py-src-string">&quot;Not in range&quot;</span>)
 514     <span class="py-src-keyword">return</span> <span class="py-src-variable">val</span>
 515 <span class="py-src-variable">oneTwoThree</span>.<span class="py-src-variable">coerceDoc</span> = <span class="py-src-string">&quot;Must be 1, 2 or 3.&quot;</span>
 516
 517 <span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">usage</span>
 518
 519 <span class="py-src-keyword">class</span> <span class="py-src-identifier">Options</span>(<span class="py-src-parameter">usage</span>.<span class="py-src-parameter">Options</span>):
 520     <span class="py-src-variable">optParameters</span> = [[<span class="py-src-string">&quot;one_choice&quot;</span>, <span class="py-src-string">&quot;o&quot;</span>, <span class="py-src-number">1</span>, <span class="py-src-variable">None</span>, <span class="py-src-variable">oneTwoThree</span>]]
 521 </pre>
 522
 523 <p>This example code will print the following help when added to your program:
 524 </p>
 525
 526 <pre class="shell" xml:space="preserve">
 527 $ python myprogram.py --help
 528 Usage: myprogram [options]
 529 Options:
 530   -o, --one_choice=           [default: 0]. Must be 1, 2 or 3.
 531 </pre>
 532     <h2>Shell tab-completion<a name="auto9"/></h2>
 533
 534     <p>The <code>Options</code> class may provide tab-completion to interactive
 535     command shells. Only <code>zsh</code> is supported at present, but there is
 536     some interest in supporting <code>bash</code> in the future.</p>
 537
 538     <p>Support is automatic for all of the commands shipped with Twisted. Zsh
 539     has shipped, for a number of years, a completion function which ties in to
 540     the support provided by the <code>Options</code> class.</p>
 541
 542     <p>If you are writing a <code>twistd</code> plugin, then tab-completion
 543     for your <code>twistd</code> sub-command is also automatic.</p>
 544
 545     <p>For other commands you may easily provide zsh tab-completion support.
 546     Copy the file &quot;twisted/python/twisted-completion.zsh&quot; and name it something
 547     like &quot;_mycommand&quot;. A leading underscore with no extension is zsh's
 548     convention for completion function files.</p>
 549
 550     <p>Edit the new file and change the first line to refer only to your new
 551     command(s), like so:</p>
 552
 553 <pre class="shell" xml:space="preserve">
 554 #compdef mycommand
 555 </pre>
 556
 557     <p>Then ensure this file is made available to the shell by placing it in
 558     one of the directories appearing in zsh's $fpath. Restart zsh, and ensure
 559     advanced completion is enabled
 560     (<code>autoload -U compinit; compinit)</code>. You should then be able to
 561     type the name of your command and press Tab to have your command-line
 562     options completed.</p>
 563
 564     <h3>Completion metadata<a name="auto10"/></h3>
 565
 566     <p>Optionally, a special attribute, <code>compData</code>, may be defined
 567     on your <code>Options</code> subclass in order to provide more information
 568     to the shell-completion system. The attribute should be an instance of
 569     <a class="API" shape="rect"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.python.usage.Completions.html" title="twisted.python.usage.Completions">Completions</a></a>. See that class
 570     for further details.</p>
 571
 572     <p>In addition, <code>compData</code> may be defined on parent classes in
 573     your inheritance hiearchy. The information from each
 574     <a class="API" shape="rect"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.python.usage.Completions.html" title="twisted.python.usage.Completions">Completions</a></a> instance will be
 575     aggregated when producing the final tab-completion results.</p>
 576   </div>
 577
 578     <p><a href="index.html">Index</a></p>
 579     <span class="version">Version: 12.1.0</span>
 580   </body>
 581 </html>