Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`python`.`usage`.`Options``

class documentation

`class Options(Dict[str, Any]): (source)`

Known subclasses: `twisted.application.app.ServerOptions`, `twisted.application.twist._options.TwistOptions`, `twisted.conch.client.options.ConchOptions`, `twisted.conch.manhole_tap.Options`, `twisted.conch.scripts.ckeygen.GeneralOptions`, `twisted.conch.scripts.tkconch.GeneralOptions`, `twisted.conch.tap.Options`, `twisted.mail.tap.Options`, `twisted.names.tap.Options`, `twisted.runner.inetdtap.Options`, `twisted.runner.procmontap.Options`, `twisted.scripts.htmlizer.Options`, `twisted.scripts.trial.Options`, `twisted.tap.ftp.Options`, `twisted.tap.portforward.Options`, `twisted.tap.socks.Options`, `twisted.trial._dist.options.WorkerOptions`, `twisted.web.tap.Options`, `twisted.words.tap.Options`, `twisted.words.xmpproutertap.Options`

View In Hierarchy

An option list parser class

`optFlags` and `optParameters` are lists of available parameters which your program can handle. The difference between the two is the 'flags' have an on(1) or off(0) state (off by default) whereas 'parameters' have an assigned value, with an optional default. (Compare '--verbose' and '--verbosity=2')

optFlags is assigned a list of lists. Each list represents a flag parameter, as so:

       optFlags = [['verbose', 'v', 'Makes it tell you what it doing.'],
                   ['quiet', 'q', 'Be vewy vewy quiet.']]

As you can see, the first item is the long option name (prefixed with '--' on the command line), followed by the short option name (prefixed with '-'), and the description. The description is used for the built-in handling of the --help switch, which prints a usage summary.

`optParameters` is much the same, except the list also contains a default value:

       optParameters = [['outfile', 'O', 'outfile.log', 'Description...']]

A coerce function can also be specified as the last element: it will be called with the argument and should return the value that will be stored for the option. This function can have a `coerceDoc` attribute which will be appended to the documentation of the option.

subCommands is a list of 4-tuples of (command name, command shortcut, parser class, documentation). If the first non-option argument found is one of the given command names, an instance of the given parser class is instantiated and given the remainder of the arguments to parse and self.opts[command] is set to the command name. For example:

       subCommands = [
            ['inquisition', 'inquest', InquisitionOptions,
                 'Perform an inquisition'],
            ['holyquest', 'quest', HolyQuestOptions,
                 'Embark upon a holy quest']
        ]

In this case, `"<program> holyquest --horseback --for-grail"` will cause `HolyQuestOptions` to be instantiated and asked to parse `['--horseback', '--for-grail']`. Currently, only the first sub-command is parsed, and all options following it are passed to its parser. If a subcommand is found, the subCommand attribute is set to its name and the subOptions attribute is set to the Option instance that parses the remaining options. If a subcommand is not given to parseOptions, the subCommand attribute will be None. You can also mark one of the subCommands to be the default:

       defaultSubCommand = 'holyquest'

In this case, the subCommand attribute will never be None, and the subOptions attribute will always be set.

If you want to handle your own options, define a method named `opt_paramname` that takes `(self, option)` as arguments. `option` will be whatever immediately follows the parameter on the command line. Options fully supports the mapping interface, so you can do things like `'self["option"] = val'` in these methods.

Shell tab-completion is supported by this class, for zsh only at present. Zsh ships with a stub file ("completion function") which, for Twisted commands, performs tab-completion on-the-fly using the support provided by this class. The stub file lives in our tree at `twisted/python/twisted-completion.zsh`, and in the Zsh tree at `Completion/Unix/Command/_twisted`.

Tab-completion is based upon the contents of the optFlags and optParameters lists. And, optionally, additional metadata may be provided by assigning a special attribute, `compData`, which should be an instance of `Completions`. See that class for details of what can and should be included - and see the howto for additional help using these features - including how third-parties may take advantage of tab-completion for their own commands.

Advanced functionality is covered in the howto documentation, available at http://twistedmatrix.com/projects/core/documentation/howto/options.html, or doc/core/howto/options.xhtml in your Twisted directory.

Method | `__init__` | Undocumented
Method | `__str__` | Undocumented
Method | `getSynopsis` | Returns a string containing a description of these options and how to pass them to the executed file.
Method | `getUsage` | Undocumented
Method | `opt_help` | Display this help and exit.
Method | `opt_version` | Display Twisted version and exit.
Method | `parseArgs` | I am called with any leftover arguments which were not options.
Method | `parseOptions` | The guts of the command-line parser.
Method | `postOptions` | I am called after the options are parsed.
Class Variable | `completionData` | Undocumented
Class Variable | `defaultSubCommand` | Undocumented
Class Variable | `parent` | Undocumented
Instance Variable | `defaults` | Undocumented
Instance Variable | `docs` | Undocumented
Instance Variable | `longOpt` | Undocumented
Instance Variable | `opts` | Undocumented
Instance Variable | `shortOpt` | Undocumented
Instance Variable | `subCommand` | Undocumented
Instance Variable | `subOptions` | Undocumented
Instance Variable | `synonyms` | Undocumented
Method | `_gather_flags` | Gather up boolean (flag) options.
Method | `_gather_handlers` | Gather up options with their own handler methods.
Method | `_gather_parameters` | Gather options which take a value.
Method | `_generic_flag` | Undocumented
Instance Variable | `_dispatch` | Undocumented

def __init__(self): (source)
overridden in `twisted.application.app.ServerOptions`, `twisted.application.twist._options.TwistOptions`, `twisted.conch.client.options.ConchOptions`, `twisted.conch.manhole_tap.Options`, `twisted.conch.tap.Options`, `twisted.mail.tap.Options`, `twisted.names.tap.Options`, `twisted.tap.ftp.Options`, `twisted.web.tap.Options`, `twisted.words.tap.Options`

Undocumented

def __str__(self) -> `str`: (source)

Undocumented

def getSynopsis(self) -> `str`: (source)
overridden in `twisted.application.twist._options.TwistOptions`

Returns a string containing a description of these options and how to pass them to the executed file.

def getUsage(self, width: `Optional[int]` = None) -> `str`: (source)

Undocumented

def opt_help(self): (source)

Display this help and exit.

def opt_version(self): (source)
overridden in `twisted.application.twist._options.TwistOptions`, `twisted.scripts._twistd_unix.ServerOptions`, `twisted.scripts._twistw.ServerOptions`

Display Twisted version and exit.

def parseArgs(self): (source)
overridden in `twisted.conch.scripts.cftp.ClientOptions`, `twisted.conch.scripts.conch.ClientOptions`, `twisted.conch.scripts.tkconch.GeneralOptions`, `twisted.runner.procmontap.Options`, `twisted.scripts.htmlizer.Options`

I am called with any leftover arguments which were not options.

Override me to do something with the remaining arguments on the command line, those which were not flags or options. e.g. interpret them as a list of files to operate on.

Note that if there more arguments on the command line than this method accepts, parseArgs will blow up with a getopt.error. This means if you don't override me, parseArgs will blow up if I am passed any arguments at all!

def parseOptions(self, options=None): (source)
overridden in `twisted.application.app.ServerOptions`, `twisted.application.twist._options.TwistOptions`

The guts of the command-line parser.

def postOptions(self): (source)
overridden in `twisted.application.app.ServerOptions`, `twisted.application.twist._options.TwistOptions`, `twisted.conch.manhole_tap.Options`, `twisted.mail.tap.Options`, `twisted.names.tap.Options`, `twisted.runner.procmontap.Options`, `twisted.scripts.trial.Options`, `twisted.web.tap.Options`

I am called after the options are parsed.

Override this method in your subclass to do something after the options have been parsed and assigned, like validate that all options are sane.

completionData = (source)

Undocumented

defaultSubCommand: `Optional[str]` = (source)

Undocumented

parent: `Optional[Options]` = (source)

Undocumented

defaults: `dict` = (source)

Undocumented

docs: `dict` = (source)

Undocumented

longOpt: `list` = (source)

Undocumented

opts = (source)

Undocumented

shortOpt = (source)

Undocumented

subCommand: `Optional[str]` = (source)

Undocumented

subOptions = (source)

Undocumented

synonyms: `dict` = (source)

Undocumented

def _gather_flags(self): (source)

Gather up boolean (flag) options.

def _gather_handlers(self): (source)

Gather up options with their own handler methods.

This returns a tuple of many values. Amongst those values is a synonyms dictionary, mapping all of the possible aliases (`str`) for an option to the longest spelling of that option's name C({str}).

Another element is a dispatch dictionary, mapping each user-facing option name (with - substituted for _) to a callable to handle that option.

def _gather_parameters(self): (source)

Gather options which take a value.

def _generic_flag(self, flagName, value=None): (source)

Undocumented

_dispatch: `dict` = (source)

Undocumented