# Copyright (c) Twisted Matrix Laboratories. # See LICENSE for details. """ Tests for L{twisted.python.usage}, a command line option parsing library. """ from twisted.python import usage from twisted.trial import unittest class WellBehaved(usage.Options): optParameters = [ ["long", "w", "default", "and a docstring"], ["another", "n", "no docstring"], ["longonly", None, "noshort"], ["shortless", None, "except", "this one got docstring"], ] optFlags = [ [ "aflag", "f", """ flagallicious docstringness for this here """, ], ["flout", "o"], ] def opt_myflag(self): self.opts["myflag"] = "PONY!" def opt_myparam(self, value): self.opts["myparam"] = f"{value} WITH A PONY!" class ParseCorrectnessTests(unittest.TestCase): """ Test L{usage.Options.parseOptions} for correct values under good conditions. """ def setUp(self): """ Instantiate and parseOptions a well-behaved Options class. """ self.niceArgV = ( "--long Alpha -n Beta " "--shortless Gamma -f --myflag " "--myparam Tofu" ).split() self.nice = WellBehaved() self.nice.parseOptions(self.niceArgV) def test_checkParameters(self): """ Parameters have correct values. """ self.assertEqual(self.nice.opts["long"], "Alpha") self.assertEqual(self.nice.opts["another"], "Beta") self.assertEqual(self.nice.opts["longonly"], "noshort") self.assertEqual(self.nice.opts["shortless"], "Gamma") def test_checkFlags(self): """ Flags have correct values. """ self.assertEqual(self.nice.opts["aflag"], 1) self.assertEqual(self.nice.opts["flout"], 0) def test_checkCustoms(self): """ Custom flags and parameters have correct values. """ self.assertEqual(self.nice.opts["myflag"], "PONY!") self.assertEqual(self.nice.opts["myparam"], "Tofu WITH A PONY!") class TypedOptions(usage.Options): optParameters = [ ["fooint", None, 392, "Foo int", int], ["foofloat", None, 4.23, "Foo float", float], ["eggint", None, None, "Egg int without default", int], ["eggfloat", None, None, "Egg float without default", float], ] def opt_under_score(self, value): """ This option has an underscore in its name to exercise the _ to - translation. """ self.underscoreValue = value opt_u = opt_under_score class TypedTests(unittest.TestCase): """ Test L{usage.Options.parseOptions} for options with forced types. """ def setUp(self): self.usage = TypedOptions() def test_defaultValues(self): """ Default values are parsed. """ argV = [] self.usage.parseOptions(argV) self.assertEqual(self.usage.opts["fooint"], 392) self.assertIsInstance(self.usage.opts["fooint"], int) self.assertEqual(self.usage.opts["foofloat"], 4.23) self.assertIsInstance(self.usage.opts["foofloat"], float) self.assertIsNone(self.usage.opts["eggint"]) self.assertIsNone(self.usage.opts["eggfloat"]) def test_parsingValues(self): """ int and float values are parsed. """ argV = ("--fooint 912 --foofloat -823.1 " "--eggint 32 --eggfloat 21").split() self.usage.parseOptions(argV) self.assertEqual(self.usage.opts["fooint"], 912) self.assertIsInstance(self.usage.opts["fooint"], int) self.assertEqual(self.usage.opts["foofloat"], -823.1) self.assertIsInstance(self.usage.opts["foofloat"], float) self.assertEqual(self.usage.opts["eggint"], 32) self.assertIsInstance(self.usage.opts["eggint"], int) self.assertEqual(self.usage.opts["eggfloat"], 21.0) self.assertIsInstance(self.usage.opts["eggfloat"], float) def test_underscoreOption(self): """ A dash in an option name is translated to an underscore before being dispatched to a handler. """ self.usage.parseOptions(["--under-score", "foo"]) self.assertEqual(self.usage.underscoreValue, "foo") def test_underscoreOptionAlias(self): """ An option name with a dash in it can have an alias. """ self.usage.parseOptions(["-u", "bar"]) self.assertEqual(self.usage.underscoreValue, "bar") def test_invalidValues(self): """ Passing wrong values raises an error. """ argV = "--fooint egg".split() self.assertRaises(usage.UsageError, self.usage.parseOptions, argV) class WrongTypedOptions(usage.Options): optParameters = [["barwrong", None, None, "Bar with wrong coerce", "he"]] class WeirdCallableOptions(usage.Options): def _bar(value): raise RuntimeError("Ouch") def _foo(value): raise ValueError("Yay") optParameters = [ ["barwrong", None, None, "Bar with strange callable", _bar], ["foowrong", None, None, "Foo with strange callable", _foo], ] class WrongTypedTests(unittest.TestCase): """ Test L{usage.Options.parseOptions} for wrong coerce options. """ def test_nonCallable(self): """ Using a non-callable type fails. """ us = WrongTypedOptions() argV = "--barwrong egg".split() self.assertRaises(TypeError, us.parseOptions, argV) def test_notCalledInDefault(self): """ The coerce functions are not called if no values are provided. """ us = WeirdCallableOptions() argV = [] us.parseOptions(argV) def test_weirdCallable(self): """ Errors raised by coerce functions are handled properly. """ us = WeirdCallableOptions() argV = "--foowrong blah".split() # ValueError is swallowed as UsageError e = self.assertRaises(usage.UsageError, us.parseOptions, argV) self.assertEqual(str(e), "Parameter type enforcement failed: Yay") us = WeirdCallableOptions() argV = "--barwrong blah".split() # RuntimeError is not swallowed self.assertRaises(RuntimeError, us.parseOptions, argV) class OutputTests(unittest.TestCase): def test_uppercasing(self): """ Error output case adjustment does not mangle options """ opt = WellBehaved() e = self.assertRaises(usage.UsageError, opt.parseOptions, ["-Z"]) self.assertEqual(str(e), "option -Z not recognized") class InquisitionOptions(usage.Options): optFlags = [ ("expect", "e"), ] optParameters = [ ("torture-device", "t", "comfy-chair", "set preferred torture device"), ] class HolyQuestOptions(usage.Options): optFlags = [ ("horseback", "h", "use a horse"), ("for-grail", "g"), ] class SubCommandOptions(usage.Options): optFlags = [ ("europian-swallow", None, "set default swallow type to Europian"), ] subCommands = [ ("inquisition", "inquest", InquisitionOptions, "Perform an inquisition"), ("holyquest", "quest", HolyQuestOptions, "Embark upon a holy quest"), ] class SubCommandTests(unittest.TestCase): """ Test L{usage.Options.parseOptions} for options with subcommands. """ def test_simpleSubcommand(self): """ A subcommand is recognized. """ o = SubCommandOptions() o.parseOptions(["--europian-swallow", "inquisition"]) self.assertTrue(o["europian-swallow"]) self.assertEqual(o.subCommand, "inquisition") self.assertIsInstance(o.subOptions, InquisitionOptions) self.assertFalse(o.subOptions["expect"]) self.assertEqual(o.subOptions["torture-device"], "comfy-chair") def test_subcommandWithFlagsAndOptions(self): """ Flags and options of a subcommand are assigned. """ o = SubCommandOptions() o.parseOptions(["inquisition", "--expect", "--torture-device=feather"]) self.assertFalse(o["europian-swallow"]) self.assertEqual(o.subCommand, "inquisition") self.assertIsInstance(o.subOptions, InquisitionOptions) self.assertTrue(o.subOptions["expect"]) self.assertEqual(o.subOptions["torture-device"], "feather") def test_subcommandAliasWithFlagsAndOptions(self): """ Flags and options of a subcommand alias are assigned. """ o = SubCommandOptions() o.parseOptions(["inquest", "--expect", "--torture-device=feather"]) self.assertFalse(o["europian-swallow"]) self.assertEqual(o.subCommand, "inquisition") self.assertIsInstance(o.subOptions, InquisitionOptions) self.assertTrue(o.subOptions["expect"]) self.assertEqual(o.subOptions["torture-device"], "feather") def test_anotherSubcommandWithFlagsAndOptions(self): """ Flags and options of another subcommand are assigned. """ o = SubCommandOptions() o.parseOptions(["holyquest", "--for-grail"]) self.assertFalse(o["europian-swallow"]) self.assertEqual(o.subCommand, "holyquest") self.assertIsInstance(o.subOptions, HolyQuestOptions) self.assertFalse(o.subOptions["horseback"]) self.assertTrue(o.subOptions["for-grail"]) def test_noSubcommand(self): """ If no subcommand is specified and no default subcommand is assigned, a subcommand will not be implied. """ o = SubCommandOptions() o.parseOptions(["--europian-swallow"]) self.assertTrue(o["europian-swallow"]) self.assertIsNone(o.subCommand) self.assertFalse(hasattr(o, "subOptions")) def test_defaultSubcommand(self): """ Flags and options in the default subcommand are assigned. """ o = SubCommandOptions() o.defaultSubCommand = "inquest" o.parseOptions(["--europian-swallow"]) self.assertTrue(o["europian-swallow"]) self.assertEqual(o.subCommand, "inquisition") self.assertIsInstance(o.subOptions, InquisitionOptions) self.assertFalse(o.subOptions["expect"]) self.assertEqual(o.subOptions["torture-device"], "comfy-chair") def test_subCommandParseOptionsHasParent(self): """ The parseOptions method from the Options object specified for the given subcommand is called. """ class SubOpt(usage.Options): def parseOptions(self, *a, **kw): self.sawParent = self.parent usage.Options.parseOptions(self, *a, **kw) class Opt(usage.Options): subCommands = [ ("foo", "f", SubOpt, "bar"), ] o = Opt() o.parseOptions(["foo"]) self.assertTrue(hasattr(o.subOptions, "sawParent")) self.assertEqual(o.subOptions.sawParent, o) def test_subCommandInTwoPlaces(self): """ The .parent pointer is correct even when the same Options class is used twice. """ class SubOpt(usage.Options): pass class OptFoo(usage.Options): subCommands = [ ("foo", "f", SubOpt, "quux"), ] class OptBar(usage.Options): subCommands = [ ("bar", "b", SubOpt, "quux"), ] oFoo = OptFoo() oFoo.parseOptions(["foo"]) oBar = OptBar() oBar.parseOptions(["bar"]) self.assertTrue(hasattr(oFoo.subOptions, "parent")) self.assertTrue(hasattr(oBar.subOptions, "parent")) self.failUnlessIdentical(oFoo.subOptions.parent, oFoo) self.failUnlessIdentical(oBar.subOptions.parent, oBar) class HelpStringTests(unittest.TestCase): """ Test generated help strings. """ def setUp(self): """ Instantiate a well-behaved Options class. """ self.niceArgV = ( "--long Alpha -n Beta " "--shortless Gamma -f --myflag " "--myparam Tofu" ).split() self.nice = WellBehaved() def test_noGoBoom(self): """ __str__ shouldn't go boom. """ try: self.nice.__str__() except Exception as e: self.fail(e) def test_whitespaceStripFlagsAndParameters(self): """ Extra whitespace in flag and parameters docs is stripped. """ # We test this by making sure aflag and it's help string are on the # same line. lines = [s for s in str(self.nice).splitlines() if s.find("aflag") >= 0] self.assertTrue(len(lines) > 0) self.assertTrue(lines[0].find("flagallicious") >= 0) class PortCoerceTests(unittest.TestCase): """ Test the behavior of L{usage.portCoerce}. """ def test_validCoerce(self): """ Test the answers with valid input. """ self.assertEqual(0, usage.portCoerce("0")) self.assertEqual(3210, usage.portCoerce("3210")) self.assertEqual(65535, usage.portCoerce("65535")) def test_errorCoerce(self): """ Test error path. """ self.assertRaises(ValueError, usage.portCoerce, "") self.assertRaises(ValueError, usage.portCoerce, "-21") self.assertRaises(ValueError, usage.portCoerce, "212189") self.assertRaises(ValueError, usage.portCoerce, "foo") class ZshCompleterTests(unittest.TestCase): """ Test the behavior of the various L{twisted.usage.Completer} classes for producing output usable by zsh tab-completion system. """ def test_completer(self): """ Completer produces zsh shell-code that produces no completion matches. """ c = usage.Completer() got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ":some-option:") c = usage.Completer(descr="some action", repeat=True) got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, "*:some action:") def test_files(self): """ CompleteFiles produces zsh shell-code that completes file names according to a glob. """ c = usage.CompleteFiles() got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ':some-option (*):_files -g "*"') c = usage.CompleteFiles("*.py") got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ':some-option (*.py):_files -g "*.py"') c = usage.CompleteFiles("*.py", descr="some action", repeat=True) got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, '*:some action (*.py):_files -g "*.py"') def test_dirs(self): """ CompleteDirs produces zsh shell-code that completes directory names. """ c = usage.CompleteDirs() got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ":some-option:_directories") c = usage.CompleteDirs(descr="some action", repeat=True) got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, "*:some action:_directories") def test_list(self): """ CompleteList produces zsh shell-code that completes words from a fixed list of possibilities. """ c = usage.CompleteList("ABC") got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ":some-option:(A B C)") c = usage.CompleteList(["1", "2", "3"]) got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ":some-option:(1 2 3)") c = usage.CompleteList(["1", "2", "3"], descr="some action", repeat=True) got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, "*:some action:(1 2 3)") def test_multiList(self): """ CompleteMultiList produces zsh shell-code that completes multiple comma-separated words from a fixed list of possibilities. """ c = usage.CompleteMultiList("ABC") got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ":some-option:_values -s , 'some-option' A B C") c = usage.CompleteMultiList(["1", "2", "3"]) got = c._shellCode("some-option", usage._ZSH) self.assertEqual(got, ":some-option:_values -s , 'some-option' 1 2 3") c = usage.CompleteMultiList(["1", "2", "3"], descr="some action", repeat=True) got = c._shellCode("some-option", usage._ZSH) expected = "*:some action:_values -s , 'some action' 1 2 3" self.assertEqual(got, expected) def test_usernames(self): """ CompleteUsernames produces zsh shell-code that completes system usernames. """ c = usage.CompleteUsernames() out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, ":some-option:_users") c = usage.CompleteUsernames(descr="some action", repeat=True) out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, "*:some action:_users") def test_groups(self): """ CompleteGroups produces zsh shell-code that completes system group names. """ c = usage.CompleteGroups() out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, ":group:_groups") c = usage.CompleteGroups(descr="some action", repeat=True) out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, "*:some action:_groups") def test_hostnames(self): """ CompleteHostnames produces zsh shell-code that completes hostnames. """ c = usage.CompleteHostnames() out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, ":some-option:_hosts") c = usage.CompleteHostnames(descr="some action", repeat=True) out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, "*:some action:_hosts") def test_userAtHost(self): """ CompleteUserAtHost produces zsh shell-code that completes hostnames or a word of the form @. """ c = usage.CompleteUserAtHost() out = c._shellCode("some-option", usage._ZSH) self.assertTrue(out.startswith(":host | user@host:")) c = usage.CompleteUserAtHost(descr="some action", repeat=True) out = c._shellCode("some-option", usage._ZSH) self.assertTrue(out.startswith("*:some action:")) def test_netInterfaces(self): """ CompleteNetInterfaces produces zsh shell-code that completes system network interface names. """ c = usage.CompleteNetInterfaces() out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, ":some-option:_net_interfaces") c = usage.CompleteNetInterfaces(descr="some action", repeat=True) out = c._shellCode("some-option", usage._ZSH) self.assertEqual(out, "*:some action:_net_interfaces") class CompleterNotImplementedTests(unittest.TestCase): """ Using an unknown shell constant with the various Completer() classes should raise NotImplementedError """ def test_unknownShell(self): """ Using an unknown shellType should raise NotImplementedError """ classes = [ usage.Completer, usage.CompleteFiles, usage.CompleteDirs, usage.CompleteList, usage.CompleteMultiList, usage.CompleteUsernames, usage.CompleteGroups, usage.CompleteHostnames, usage.CompleteUserAtHost, usage.CompleteNetInterfaces, ] for cls in classes: try: action = cls() except BaseException: action = cls(None) self.assertRaises( NotImplementedError, action._shellCode, None, "bad_shell_type" ) class FlagFunctionTests(unittest.TestCase): """ Tests for L{usage.flagFunction}. """ class SomeClass: """ Dummy class for L{usage.flagFunction} tests. """ def oneArg(self, a): """ A one argument method to be tested by L{usage.flagFunction}. @param a: a useless argument to satisfy the function's signature. """ def noArg(self): """ A no argument method to be tested by L{usage.flagFunction}. """ def manyArgs(self, a, b, c): """ A multiple arguments method to be tested by L{usage.flagFunction}. @param a: a useless argument to satisfy the function's signature. @param b: a useless argument to satisfy the function's signature. @param c: a useless argument to satisfy the function's signature. """ def test_hasArg(self): """ L{usage.flagFunction} returns C{False} if the method checked allows exactly one argument. """ self.assertIs(False, usage.flagFunction(self.SomeClass().oneArg)) def test_noArg(self): """ L{usage.flagFunction} returns C{True} if the method checked allows exactly no argument. """ self.assertIs(True, usage.flagFunction(self.SomeClass().noArg)) def test_tooManyArguments(self): """ L{usage.flagFunction} raises L{usage.UsageError} if the method checked allows more than one argument. """ exc = self.assertRaises( usage.UsageError, usage.flagFunction, self.SomeClass().manyArgs ) self.assertEqual("Invalid Option function for manyArgs", str(exc)) def test_tooManyArgumentsAndSpecificErrorMessage(self): """ L{usage.flagFunction} uses the given method name in the error message raised when the method allows too many arguments. """ exc = self.assertRaises( usage.UsageError, usage.flagFunction, self.SomeClass().manyArgs, "flubuduf" ) self.assertEqual("Invalid Option function for flubuduf", str(exc)) class OptionsInternalTests(unittest.TestCase): """ Tests internal behavior of C{usage.Options}. """ def test_optionsAliasesOrder(self): """ Options which are synonyms to another option are aliases towards the longest option name. """ class Opts(usage.Options): def opt_very_very_long(self): """ This is an option method with a very long name, that is going to be aliased. """ opt_short = opt_very_very_long opt_s = opt_very_very_long opts = Opts() self.assertEqual( dict.fromkeys(["s", "short", "very-very-long"], "very-very-long"), { "s": opts.synonyms["s"], "short": opts.synonyms["short"], "very-very-long": opts.synonyms["very-very-long"], }, )