Ticket #7683: 7683-1.patch

File 7683-1.patch, 10.9 KB (added by Jonathan Ballet, 3 years ago)
  • docs/core/howto/options.rst

    diff --git docs/core/howto/options.rst docs/core/howto/options.rst
    index 3064386..2631467 100644
    Completion metadata 
    627627Optionally, a special attribute, ``compData`` , may be defined
    628628on your ``Options`` subclass in order to provide more information
    629629to the shell-completion system. The attribute should be an instance of
    630 I DON'T KNOW WHAT TO DO WITH THIS LINK!
     630:api:`twisted.python.usage.Completions <twisted.python.usage.Completions>`. See
     631that class for further details.
    631632
    632633   
    633634
    634635
    635636In addition, ``compData`` may be defined on parent classes in
    636637your inheritance hiearchy. The information from each
    637 I DON'T KNOW WHAT TO DO WITH THIS LINK!
     638:api:`twisted.python.usage.Completions <twisted.python.usage.Completions>`
     639instance will be aggregated when producing the final tab-completion results.
    638640 
    639641
  • twisted/python/usage.py

    diff --git twisted/python/usage.py twisted/python/usage.py
    index 9aef363..d8102fd 100644
    command line of your program. 
    99
    1010For information on how to use it, see
    1111U{http://twistedmatrix.com/projects/core/documentation/howto/options.html},
    12 or doc/core/howto/options.xhtml in your Twisted directory.
     12or C{doc/core/howto/options.rst} in your Twisted directory.
    1313"""
    1414
    1515from __future__ import print_function
    class Options(dict): 
    6969
    7070    C{optFlags} and C{optParameters} are lists of available parameters
    7171    which your program can handle. The difference between the two
    72     is the 'flags' have an on(1) or off(0) state (off by default)
    73     whereas 'parameters' have an assigned value, with an optional
    74     default. (Compare '--verbose' and '--verbosity=2')
     72    is the C{flags} have an on(1) or off(0) state (off by default)
     73    whereas C{parameters} have an assigned value, with an optional
     74    default. (Compare C{--verbose} and C{--verbosity=2})
    7575
    76     optFlags is assigned a list of lists. Each list represents
     76    C{optFlags} is assigned a list of lists. Each list represents
    7777    a flag parameter, as so::
    7878
    79     |    optFlags = [['verbose', 'v', 'Makes it tell you what it doing.'],
    80     |                ['quiet', 'q', 'Be vewy vewy quiet.']]
     79        optFlags = [['verbose', 'v', 'Makes it tell you what it doing.'],
     80                    ['quiet', 'q', 'Be vewy vewy quiet.']]
    8181
    8282    As you can see, the first item is the long option name
    83     (prefixed with '--' on the command line), followed by the
    84     short option name (prefixed with '-'), and the description.
     83    (prefixed with C{--} on the command line), followed by the
     84    short option name (prefixed with C{-}), and the description.
    8585    The description is used for the built-in handling of the
    86     --help switch, which prints a usage summary.
     86    C{--help} switch, which prints a usage summary.
    8787
    8888    C{optParameters} is much the same, except the list also contains
    8989    a default value::
    9090
    91     | optParameters = [['outfile', 'O', 'outfile.log', 'Description...']]
     91        optParameters = [['outfile', 'O', 'outfile.log', 'Description...']]
    9292
    9393    A coerce function can also be specified as the last element: it will be
    9494    called with the argument and should return the value that will be stored
    9595    for the option. This function can have a C{coerceDoc} attribute which
    9696    will be appended to the documentation of the option.
    9797
    98     subCommands is a list of 4-tuples of (command name, command shortcut,
     98    C{subCommands} is a list of 4-tuples of (command name, command shortcut,
    9999    parser class, documentation).  If the first non-option argument found is
    100100    one of the given command names, an instance of the given parser class is
    101101    instantiated and given the remainder of the arguments to parse and
    102     self.opts[command] is set to the command name.  For example::
     102    C{self.opts[command]} is set to the command name.  For example::
    103103
    104     | subCommands = [
    105     |      ['inquisition', 'inquest', InquisitionOptions,
    106     |           'Perform an inquisition'],
    107     |      ['holyquest', 'quest', HolyQuestOptions,
    108     |           'Embark upon a holy quest']
    109     |  ]
     104        subCommands = [
     105             ['inquisition', 'inquest', InquisitionOptions,
     106                  'Perform an inquisition'],
     107             ['holyquest', 'quest', HolyQuestOptions,
     108                  'Embark upon a holy quest']
     109        ]
    110110
    111     In this case, C{"<program> holyquest --horseback --for-grail"} will cause
     111    In this case, C{"holyquest --horseback --for-grail"} will cause
    112112    C{HolyQuestOptions} to be instantiated and asked to parse
    113113    C{['--horseback', '--for-grail']}.  Currently, only the first sub-command
    114114    is parsed, and all options following it are passed to its parser.  If a
    115     subcommand is found, the subCommand attribute is set to its name and the
     115    subcommand is found, the C{subCommand} attribute is set to its name and the
    116116    subOptions attribute is set to the Option instance that parses the
    117     remaining options. If a subcommand is not given to parseOptions,
    118     the subCommand attribute will be None. You can also mark one of
    119     the subCommands to be the default.
     117    remaining options. If a subcommand is not given to C{parseOptions},
     118    the C{subCommand} attribute will be C{None}. You can also mark one of
     119    the C{subCommands} to be the default::
    120120
    121     | defaultSubCommand = 'holyquest'
     121        defaultSubCommand = 'holyquest'
    122122
    123     In this case, the subCommand attribute will never be None, and
    124     the subOptions attribute will always be set.
     123    In this case, the C{subCommand} attribute will never be C{None}, and
     124    the C{subOptions} attribute will always be set.
    125125
    126126    If you want to handle your own options, define a method named
    127127    C{opt_paramname} that takes C{(self, option)} as arguments. C{option}
    128128    will be whatever immediately follows the parameter on the
    129     command line. Options fully supports the mapping interface, so you
     129    command line. L{Options} fully supports the mapping interface, so you
    130130    can do things like C{'self["option"] = val'} in these methods.
    131131
    132132    Shell tab-completion is supported by this class, for zsh only at present.
    class Options(dict): 
    136136    C{twisted/python/twisted-completion.zsh}, and in the Zsh tree at
    137137    C{Completion/Unix/Command/_twisted}.
    138138
    139     Tab-completion is based upon the contents of the optFlags and optParameters
    140     lists. And, optionally, additional metadata may be provided by assigning a
    141     special attribute, C{compData}, which should be an instance of
    142     C{Completions}. See that class for details of what can and should be
     139    Tab-completion is based upon the contents of the C{optFlags} and
     140    C{optParameters} lists. And, optionally, additional metadata may be provided
     141    by assigning a special attribute, C{compData}, which should be an instance
     142    of L{Completions}. See that class for details of what can and should be
    143143    included - and see the howto for additional help using these features -
    144144    including how third-parties may take advantage of tab-completion for their
    145145    own commands.
    class Options(dict): 
    147147    Advanced functionality is covered in the howto documentation,
    148148    available at
    149149    U{http://twistedmatrix.com/projects/core/documentation/howto/options.html},
    150     or doc/core/howto/options.xhtml in your Twisted directory.
     150    or C{doc/core/howto/options.rst} in your Twisted directory.
    151151    """
    152152
    153153    subCommand = None
    class Options(dict): 
    294294        interpret them as a list of files to operate on.
    295295
    296296        Note that if there more arguments on the command line
    297         than this method accepts, parseArgs will blow up with
    298         a getopt.error.  This means if you don't override me,
    299         parseArgs will blow up if I am passed any arguments at
     297        than this method accepts, C{parseArgs} will blow up with
     298        a C{getopt.error}.  This means if you don't override me,
     299        C{parseArgs} will blow up if I am passed any arguments at
    300300        all!
    301301        """
    302302
    class Completer(object): 
    568568
    569569        @type repeat: C{bool}
    570570        @param repeat: A flag, defaulting to False, indicating whether this
    571             C{Completer} should repeat - that is, be used to complete more
     571            L{Completer} should repeat - that is, be used to complete more
    572572            than one command-line word. This may ONLY be set to True for
    573             actions in the C{extraActions} keyword argument to C{Completions}.
     573            actions in the C{extraActions} keyword argument to L{Completions}.
    574574            And ONLY if it is the LAST (or only) action in the C{extraActions}
    575575            list.
    576576        """
    class Completions(object): 
    794794             "colors" : CompleteMultiList(["red", "green", "blue"])}
    795795
    796796        Callables may instead be given for the values in this dict. The
    797         callable should accept no arguments, and return a C{Completer}
     797        callable should accept no arguments, and return a L{Completer}
    798798        instance used as the action in the same way as the literal actions in
    799799        the example above.
    800800
    class Completions(object): 
    825825    @ivar extraActions: Extra arguments are those arguments typically
    826826        appearing at the end of the command-line, which are not associated
    827827        with any particular named option. That is, the arguments that are
    828         given to the parseArgs() method of your usage.Options subclass. For
     828        given to the L{parseArgs} method of your L{usage.Options} subclass. For
    829829        example::
     830
    830831            [CompleteFiles(descr="file to read from"),
    831832             Completer(descr="book title")]
    832833
    class Completions(object): 
    835836        2nd non-option argument will be described as "book title", but no
    836837        actual completion matches will be produced.
    837838
    838         See the various C{Completer} subclasses for other types of things which
     839        See the various L{Completer} subclasses for other types of things which
    839840        may be tab-completed (users, groups, network interfaces, etc).
    840841
    841842        Also note the C{repeat=True} flag which may be passed to any of the
    842         C{Completer} classes. This is set to allow the C{Completer} instance
    843         to be re-used for subsequent command-line words. See the C{Completer}
     843        L{Completer} classes. This is set to allow the L{Completer} instance
     844        to be re-used for subsequent command-line words. See the L{Completer}
    844845        docstring for details.
    845846    """
    846847    def __init__(self, descriptions={}, multiUse=[],
  • twisted/test/test_usage.py

    diff --git twisted/test/test_usage.py twisted/test/test_usage.py
    index be136e8..4c75203 100644
    class PortCoerceTestCase(unittest.TestCase): 
    434434
    435435class ZshCompleterTestCase(unittest.TestCase):
    436436    """
    437     Test the behavior of the various L{twisted.usage.Completer} classes
     437    Test the behavior of the various L{twisted.python.usage.Completer} classes
    438438    for producing output usable by zsh tab-completion system.
    439439    """
    440440    def test_completer(self):