U ÝáhsŽã@s„dZddlZddlmZmZmZGdd„deƒZGdd„deƒZ Gdd „d e ƒZ Gd d „d e ƒZ Gd d „d e ƒZGdd„deƒZdS)a-The commandlines.library module contains the Command, Arguments, Definitions, Mops, MultiDefinitions, and Switches classes. These objects are used to parse command line argument strings to command line syntax specific Python objects. The Command class is a high level object that is intended to be the public facing portion of the library. The commandlines Command object can be imported into projects with the following import statement: `from commandlines import Command` Exceptions raised by this module are in the `commandlines.exceptions` module. éN)ÚIndexOutOfRangeErrorÚMissingArgumentErrorÚMissingDictionaryKeyErrorc@s*eZdZdZdd„Zdd„Zdd„Zdd „Zd d „Zd d „Z dd„Z dd„Z dd„Z dd„Z dd„Zdd„Zdd„Zdd„Zdd„Zd d!„Zd"d#„Zd$d%„Zd&d'„Zd(d)„Zd*d+„ZdJd-d.„Zd/d0„Zd1d2„Zd3d4„Zd5d6„Zd7d8„Zd9d:„Zd;d<„Z d=d>„Z!d?d@„Z"dAdB„Z#dCdD„Z$dEdF„Z%dGdH„Z&dIS)KÚCommanda€An object that maintains syntax specific components of a command line string and provides methods to support the development of Python command line applications. The class is instantiated from the list of command line arguments that are passed to a Python script in `sys.argv`. Attributes: arg0 : (string) Argument at index position 0 arg1 : (string) Argument at index position 1 arg2 : (string) Argument at index position 2 arg3 : (string) Argument at index position 3 arg4 : (string) Argument at index position 4 argc : (int) Length of the arguments list arglp : (string) Argument at last index position in the arguments list arguments: (Arguments, list) List of all ordered positional arguments in the command string defaults: (dict) Dictionary of default key : value mapped as option : argument value defs: (Definitions, dict) Dictionary of key=option : value=argument definition pairs mdefs: (MultiDefinitions, Definitions, dict) Dictionary of key=option : value=argument definition pairs for options included more than once in command mops: (set) Set of multi-option short syntax (i.e. single dash) switches subcmd: (string) The first positional argument (=arg0) subsubcmd: (string) The second positional argument (=arg1) switches: (set) Set of long and short switch syntax arguments cCstjdd…|_t|jƒ|_i|_t|jƒ|_t|jƒ|_t |jƒ|_ t |jƒ|_ t |jƒ|_|j d¡|_|j d¡|_|j d¡|_|j d¡|_|j d¡|_|j |jd¡|_|j|_|j|_t |jƒdk|_t |jƒdk|_t |jƒdk|_t |j ƒdk|_t |j ƒdk|_dS)Nérééé)ÚsysÚargvÚ ArgumentsÚ argumentsÚdefaultsÚSwitchesÚswitchesÚMopsÚmopsÚ DefinitionsÚdefsÚMultiDefinitionsÚmdefsÚlenÚargcÚget_argument_for_commandobjÚarg0Úarg1Úarg2Úarg3Úarg4ÚarglpÚsubcmdÚ subsubcmdZhas_argsZ has_switchesZhas_mopsZhas_defsZ has_mdefs©Úself©r$úF/var/www/html/venv/lib/python3.8/site-packages/commandlines/library.pyÚ__init__9s*      zCommand.__init__cCsd|j ¡S©Nz0< Command object > instantiated from arguments: ©r Ú__str__r"r$r$r%Ú__repr__RszCommand.__repr__cCsd|j ¡Sr'r(r"r$r$r%r)UszCommand.__str__cCs |jdkS)zŠCommand string validation for missing arguments to the executable. :returns: boolean. True = does not validate. False = validatesr©rr"r$r$r%Údoes_not_validate_missing_args^sz&Command.does_not_validate_missing_argscCst|jƒdkot|jƒdkS)z‹Command string validation for missing definitions to the executable :returns: boolean. True = does not validate. False = validatesr)rrrr"r$r$r%Údoes_not_validate_missing_defsesz&Command.does_not_validate_missing_defscCst|jƒdkS)z£Command string validation for missing multi-option short syntax arguments to the executable :returns: boolean. True = does not validate. False = validatesr©rrr"r$r$r%Údoes_not_validate_missing_mopslsz&Command.does_not_validate_missing_mopscCst|jƒdkS)zˆCommand string validation for missing switches to the executable :returns: boolean. True = does not validate. False = validatesr©rrr"r$r$r%Ú"does_not_validate_missing_switchesssz*Command.does_not_validate_missing_switchescCs|j|krdSdSdS)zóCommand string validation for inclusion of exactly n arguments to executable. :param number: (integer) Defines the number of expected arguments for this test :returns: boolean. True = does not validate. False = validatesFTNr+©r#Únumberr$r$r%Údoes_not_validate_n_argszs z Command.does_not_validate_n_argscCs |jdkS)z›Command string validation for inclusion of at least one argument to the executable :returns: boolean. True = validates. False = does not validate.rr+r"r$r$r%Úvalidates_includes_args…szCommand.validates_includes_argscCst|jƒdkS)z¯Command string validation for inclusion of at least one definition (option-argument) to the executable :returns: boolean. True = validates. False = does not validate.r)rrr"r$r$r%Úvalidates_includes_definitionsŒsz&Command.validates_includes_definitionscCst|jƒdkS)z¾Command string validation for inclusion of at least one multi-option short syntax argument to the executable. :returns: boolean. True = validates. False = does not validate.rr.r"r$r$r%Úvalidates_includes_mops“szCommand.validates_includes_mopscCst|jƒdkS)z£Command string validation for inclusion of at least one switch argument to the executable. :returns: boolean. True = validates. False = does not validate.rr0r"r$r$r%Úvalidates_includes_switches›sz#Command.validates_includes_switchescCs |j|kS)zúCommand string validation for inclusion of exactly `number` arguments to the executable. :param number: (integer) Defines the number of expected arguments for this test :returns: boolean. True = validates. False = does not validate.r+r2r$r$r%Úvalidates_includes_n_args¢sz!Command.validates_includes_n_argscCs|j |¡dS)atSets default option : argument definitions with a dictionary parameter. The option keys should not include dashes at the beginning of the option string. One or more key:value pairs can be included in the default_dictionary parameter. :param default_dictionary: (dict) Defines the default key=option : value=argument mapping :returns: NoneN)rÚupdate)r#Zdefault_dictionaryr$r$r%Ú set_defaults°szCommand.set_defaultscGs$|D]}||j ¡krqdSqdS)a.Tests for the presence of one or more default option : argument definitions in the Command.defaults parameter :param default_needles: (tuple) One or more test default option strings :returns: boolean. True = the default options are defined. False = the default options are not definedFT)rÚkeys)r#Zdefault_needlesÚneedler$r$r%Úcontains_defaultsºs zCommand.contains_defaultscCs$||j ¡kr|j|St|ƒ‚dS)aGets the value for an existing default option : argument definition in the Command.defaults parameter. The default_needle option string should not include dashes at the beginning of the string. :param default_needle: (string) The existing default option for which a value is requested :returns: User-specified type. A value of any type that is permissible as a value in Python dictionaries :raises: MissingDictionaryKeyError if the key is not found in the Command.defaults dictionaryN)rr<r)r#Zdefault_needler$r$r%Ú get_defaultÇs zCommand.get_defaultcGs |j |¡S)ahTest for the presence of one or more switches in the command string. Returns boolean that indicates presence (True) or absence (False) of switches. Dashes should not be used at the beginning of the strings in the `switch_needles` parameter. :param switch_needles: (tuple) One or more expected switch strings. :returns: boolean)rÚcontains)r#Zswitch_needlesr$r$r%Úcontains_switchesÚszCommand.contains_switchescGs |j |¡S)zôReturns boolean that indicates presence (True) or absence (False) of one or more multi-option short syntax switch characters. :type mops_needles: tuple of one or more expected single character switches :returns: boolean)rr@)r#Z mops_needlesr$r$r%Ú contains_mopsäszCommand.contains_mopscGs |j |¡S)aŠTest for the presence of one or more option-argument definitions in the command string. Returns boolean that indicates presence (True) or absence (False) of definition options. Dashes should not be used at the beginning of the strings in the `def_needles` parameter. :param def_needles: (tuple) One or more expected definition option key(s). :returns: boolean)rr@©r#Z def_needlesr$r$r%Úcontains_definitionsíszCommand.contains_definitionscGs |j |¡S)aÛTest for the presence of multiple option-argument definitions that use the same option string. An example is `$ executable -o file1 -o file2` The dashes in the argument strings should not be included in the `def_needles` parameter. Returns boolean that indicates presence (True) or absence (False) of one or more multi-definition options. :param def_needles: (tuple) One or more expected definition option key(s). :returns: boolean)rr@rCr$r$r%Úcontains_multi_definitions÷s z"Command.contains_multi_definitionscGsJt|ƒt|jƒkrdSd}|D]"}|j||kr:|d7}qdSqdSdS)a$Test for a sequence of command line tokens in the command string. The test begins at index position 0 of the argument list and is case-sensitive. :param cmd_list: (tuple) Expected commands in expected order starting at Command.argv index position 0 :returns: booleanFrrTN)rr )r#Zcmd_listÚindexÚtest_argr$r$r%Úhas_command_sequences zCommand.has_command_sequencercCs>||jkr2|j |¡}t|jƒ||kr,dSdSnt|ƒ‚dS)aüTest for the presence of at least one (default) positional arguments following an existing argument (argument_needle). The number of expected arguments is modified by defining the `number` method parameter. :param number: (integer) The number of expected arguments after the test argument :param argument_needle: (string) The test argument that is known to be present in the command :raises: MissingArgumentError when argument_needle is not found in the parsed argument listTFN)r Úget_arg_positionrr r)r#Zargument_needler3Úpositionr$r$r%Úhas_args_afters   zCommand.has_args_aftercCs@||jkr4|j |¡}|j |¡}||kr.dSdSnt|ƒ‚dS)aTest for the presence of a supported argument in the n+1 index position for a known argument at the n position. start_argument is called as the full argument string including any expected dashes. :param start_argument: (string) The argument string including any beginning dashes as used on the command line. :param supported_at_next_position: (list) list of strings that define supported arguments in the n+1 index :raises: MissingArgumentError when start_argument is not found in the parsed argument listTFN)r rIÚ get_arg_nextr)r#Zstart_argumentZsupported_at_next_positionrJZ test_argumentr$r$r%Únext_arg_is_in's   zCommand.next_arg_is_incCsd|jkrdSdSdS)z§Test for the presence of the double dash `--` command line idiom. :returns: boolean. True = has double dash token. False = does not contain double dash token.ú--TFN)r r"r$r$r%Úhas_double_dash?s zCommand.has_double_dashcCs |j |¡S)aReturns the argument to an option that is part of an option-argument definition pair. :param def_needle: (string) The option string of the option-argument pair :returns: string :raises: MissingDictionaryKeyError when the option string is not found)rÚget_def_argument©r#Z def_needler$r$r%Úget_definitionOszCommand.get_definitioncCs |j |¡S)akReturns a list of argument strings to an option that is included multiple times using option-argument syntax on the command line (e.g. `$ executable -o file1 -o file2`) :param def_needle: (string) The option string of the option-argument pair :returns: string :raises: MissingDictionaryKeyError when the option string is not found)rrPrQr$r$r%Úget_multiple_definitionsXsz Command.get_multiple_definitionscCs.||jkr"|j |¡}|j |¡St|ƒ‚dS)a‰Returns the next positional argument at index position n + 1 to a command line argument at index position n. :param target_arg: (string) Argument string for the test. :returns: string :raises: MissingArgumentError when target_arg is not found in the parsed argument list :raises: IndexOutOfRangeError when target_arg is the last positional argumentN)r r rIrLr)r#Z target_argZrecipient_positionr$r$r%Ú get_arg_afterbs   zCommand.get_arg_aftercCs8d|jkr,|j d¡}|d}|j|d…Stdƒ‚dS)zqReturns the arguments after the double dash `--` command line idiom as a list. :returns: list of stringsrNrN)r rIr)r#Z dd_positionZstart_positionr$r$r%Úget_double_dash_argsps   zCommand.get_double_dash_argscCs d|jksd|jkrdSdSdS)z“Tests for `-h` and `--help` options in command string :returns: boolean. True = included help option. False = did not include help option.ÚhelpÚhTFN©rr"r$r$r%Úis_help_requestƒszCommand.is_help_requestcCsd|jkrdSdSdS)zTests for `--quiet` option in command string :returns: boolean. True = included quiet option. False = did not include quiet option.ÚquietTFNrXr"r$r$r%Úis_quiet_requests zCommand.is_quiet_requestcCsd|jkrdSdSdS)zŒTests for `--usage` option in command string :returns: boolean. True = included usage option. False = did not include usage option.ÚusageTFNrXr"r$r$r%Úis_usage_request—s zCommand.is_usage_requestcCsd|jkrdSdSdS)z’Tests for `--verbose` option in command string :returns: boolean. True = included verbose option. False = did not include verbose option.ÚverboseTFNrXr"r$r$r%Úis_verbose_request¡s zCommand.is_verbose_requestcCs d|jksd|jkrdSdSdS)zTests for `-v` and `--version` options in command string. :returns: boolean. True = included version option. False = did not include version option.ÚversionÚvTFNrXr"r$r$r%Úis_version_request«szCommand.is_version_requestcCsVdt|jƒ}|ddt|jƒ}|ddt|jƒ}|ddt|jƒ}|ddt|jƒ}|ddt|jƒ}|ddt|jƒ}|dd | |j ¡}|dd | |j ¡}|dd | |j ¡}|dd | |j ¡}|dd | |j ¡}|dd| |j¡}|dd| |j¡}|dd| |j¡}|S)zÛReturns a string of the instance attributes of the Command object intended for standard output use. Print the returned string to view the parsed arguments in the standard output stream. :returns: stringz obj.argc = Ú zobj.arguments = zobj.defaults = zobj.switches = z obj.defs = z obj.mdefs = z obj.mops = z obj.arg0 = z obj.arg1 = z obj.arg2 = z obj.arg3 = z obj.arg4 = z obj.arglp = z obj.subcmd = zobj.subsubcmd = )Ústrrr rrrrrÚ_get_obj_string_format_argrrrrrrr r!©r#Z the_stringr$r$r%Ú obj_string»s zCommand.obj_stringcCs|dkr dSd|dSdS)zNFormats argument strings for standard output display :returns: stringÚz''ú'Nr$rfr$r$r%reÓsz"Command._get_obj_string_format_argN)r)'Ú__name__Ú __module__Ú __qualname__Ú__doc__r&r*r)r,r-r/r1r4r5r6r7r8r9r;r>r?rArBrDrErHrKrMrOrRrSrTrUrYr[r]r_rbrgrer$r$r$r%rsH%               rc@sPeZdZdZdd„Zdd„Zdd„Zdd „Zd d „Zd d „Z dd„Z dd„Z dS)r aFA class that includes all command line arguments with positional argument order maintained. Instantiated with a list of command line string tokens. The class is derived from the Python list type. :param argv: A list of command line arguments that maintain the argument order that was entered on command linecCst ||¡dS©N)Úlistr&©r#r r$r$r%r&åszArguments.__init__cCsHd}t|ƒdkr*|D]}|d|d}q| ¡}| d¡}d|dS©Nrhrriú', ú,ú[ú]©rÚrstrip©r#Zargument_stringÚargumentr$r$r%r*ès  zArguments.__repr__cCsHd}t|ƒdkr*|D]}|d|d}q| ¡}| d¡}d|dSrqrvrxr$r$r%r)òs  zArguments.__str__cCs$t|ƒ|kr|dkr||SdSdS)aBAn argument parsing method for the instantation of the Command object. This is not intended for public use. Public calls should use the get_argument() method instead. :param position: The command line index position :returns: string or empty string if the index position is out of the index rangerrhN)r©r#rJr$r$r%rüsz%Arguments.get_argument_for_commandobjcCs&t|ƒ|kr|dkr||Stƒ‚dS)zÿReturns an argument string by the argument list index position. :param position: (integer) The command line index position :returns: string :raises: IndexOutOfRangeError if the requested index falls outside of the list index rangerN©rrrzr$r$r%Ú get_argumentszArguments.get_argumentcCs||kr| |¡St|ƒ‚dS)aÃReturns the index position of the `test_arg` parameter candidate argument string. The argument string should include the dashes at the beginning of the argument string that would be expected with use on the command line. :param test_arg: (string) The argument string for which the index position is requested :returns: string :raises: MissingArgumentError if the requested argument is not in the Argument listN)rFr)r#rGr$r$r%rIs  zArguments.get_arg_positioncCs&t|ƒ|dkr||dStƒ‚dS)a$Returns the next argument at index `position` + 1 in the command sequence. :param position: (integer) The argument index position in the Argument list :returns: string :raises: IndexOutOfRangeError if the `position` + 1 index falls outside of the existing index rangerNr{rzr$r$r%rL"s zArguments.get_arg_nextcCs|D]}||krqdSqdS)zñReturns boolean that indicates the presence (True) or absence (False) of a tuple of one or more test arguments. :param needle: (iterable) An iterable that contains one or more test argument strings. :returns: booleanFTr$©r#r=Zexpected_argumentr$r$r%r@.s zArguments.containsN) rjrkrlrmr&r*r)rr|rIrLr@r$r$r$r%r Þs     r c@s8eZdZdZdd„Zdd„Zdd„Zdd „Zd d „Zd S) rahA class that is instantiated with all command line switches that have the syntax `-s`, `--longswitch`, or `-onedashlong`. The class is derived from the Python set type and arguments with this syntax are saved as set items. :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line cCst || |¡¡dSrn)Úsetr&Ú_make_switch_setrpr$r$r%r&FszSwitches.__init__cCsHd}t|ƒdkr<|D]}|d|d}q| ¡}| d¡}d|dS©NrhrrirrrsÚ{Ú}rv©r#Z switch_stringÚswitchr$r$r%r*Is  zSwitches.__repr__cCsHd}t|ƒdkr<|D]}|d|d}q| ¡}| d¡}d|dSr€rvrƒr$r$r%r)Ss  zSwitches.__str__cCsJtƒ}|D]:}d|dkr d|kr |dkr0qFq | d¡}| |¡q |S)aReturns a set that includes all switches that are parsed from the command string. Used to instantiate Switch objects. :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line :returns: setú-rú=rN)r~ÚlstripÚadd)r#r Z switchsetZswitch_candidater$r$r%r]s  zSwitches._make_switch_setcCs|D]}||krqdSqdS)acReturns boolean that indicates the presence (True) or absence (False) of a tuple of test switches. Switch parameters in needle tuple should be passed without initial dash character(s) in the test switch argument name. :param needle: (iterable) An iterable that contains one or more test argument strings. :returns: booleanFTr$r}r$r$r%r@ps zSwitches.containsN) rjrkrlrmr&r*r)rr@r$r$r$r%r>s   rc@s8eZdZdZdd„Zdd„Zdd„Zdd „Zd d „Zd S) raèA class that is instantiated with unique switches from multi-option command line options that use short, single dash syntax. Examples: -rnj -tlx Each alphabetic character in the option token is parsed to a separate option token. The class is derived from the Python set type and the single character option switches are stored as set items. :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line cCst || |¡¡dSrn)r~r&Ú_make_mops_setrpr$r$r%r&Žsz Mops.__init__cCsHd}t|ƒdkr<|D]}|d|d}q| ¡}| d¡}d|dSr€rv©r#Z mops_stringr„r$r$r%r*‘s  z Mops.__repr__cCsHd}t|ƒdkr<|D]}|d|d}q| ¡}| d¡}d|dSr€rvrŠr$r$r%r)›s  z Mops.__str__cCs`tƒ}|D]P}d|dkr d|kr t|ƒdkr |ddkr | dd¡}|D]}| |¡qJq |S)a3Returns a set of multi-option short syntax option characters that are parsed from a list of ordered command string arguments in the parameter `argv`. :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line :returns: setr…rr†rrrh)r~rÚreplacerˆ)r#r ZmopssetZmops_candidater„r$r$r%r‰¥s   zMops._make_mops_setcCs|D]}||krqdSqdS)a…Returns boolean that indicates the presence (True) or absence (False) of a tuple of test Mops syntax option switches. The test strings should each be a single character without the dash that is used at the beginning of the entire token. :param needle: (iterable) An iterable that contains one or more test argument characters as strings. :returns: booleanFTr$r}r$r$r%r@¶s z Mops.containsN) rjrkrlrmr&r*r)r‰r@r$r$r$r%rs    rc@s0eZdZdZdd„Zdd„Zdd„Zdd „Zd S) ra_A class that is instantiated with all command line definition options as defined by the syntax `-s `, `--longoption `, `--longoption=`, or `-longoption `. To parse as a definition option, the argument to the option must not contain any dashes at the beginning of the argument string. For example, `-o --long` is not considered a definition option-arg pair, whereas `-o long` is. This class is derived from the Python dictionary type. The mapping is: key = option string with all dash '-' character(s) at the beginning of the string removed. Internal dashes are maintained. value = definition argument string. :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line cCst || |¡¡dSrn)Údictr&Ú_make_definitions_objrpr$r$r%r&ÙszDefinitions.__init__c Cs®i}t|ƒ}d}|D]”}d|dk}|dkr |dkr:qªnfd|krh| d¡}|d d¡}|d||<n8||dkr ||d d¡s | d¡}||d||<|d7}q|S)aöParses definition options from a list of ordered command line arguments to define the dictionary that is used to instantiate the Definitions class. Option string keys are stripped of dash characters before the first alphabetic character in the option name. :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line :returns: dictionary with {key = option string : value = definition argument string} mappingrr…TrNr†r)rÚsplitr‡Ú startswith) r#r ÚdefmapÚarglist_lengthÚcounterÚ def_candidateÚdash_truth_testÚ split_defÚ cleaned_keyr$r$r%rÜs$     z!Definitions._make_definitions_objcCs"|D]}|| ¡krqdSqdS)aÞReturns boolean that indicates the presence (True) or absence (False) of a tuple of option-argument definitions by option match attempt. The definition option string should be used without any initial dash characters in the definition argument name in contrast to how they were used on the command line. :param needle: (tuple) A tuple of one or more option strings from expected definition option-argument string pairs :returns: booleanFT)r<)r#r=Zexpected_definitionr$r$r%r@ÿs  zDefinitions.containscCs || ¡kr||St|ƒ‚dS)aãReturns the definition argument string for a definition option test. The needle parameter should not include dash characters at the beginning of the option string (i.e. use 'test' rather than '--test' and 't' rather than '-t'). :param needle: (string) The requested option string from the definition option-argument pair. :returns: string :raises: MissingDictionaryKeyError if the option needle is not a key defined in the Definitions objectN)r<r)r#r=r$r$r%rPs zDefinitions.get_def_argumentN)rjrkrlrmr&rr@rPr$r$r$r%rÇs #rc@s eZdZdZdd„Zdd„ZdS)rasA class that is used to parse option-argument definitions from a command line argument list where command line use includes multiple same option strings with different argument definitions. An example is: `$ executable -o file1 -o file2` The class is derived from the commandlines.Definitions class (which is derived from Python dict). The commandlines.Definitions.contains and commandlines.Definitions.get_def_arguments methods are inherited from the Definitions class. The dictionary mapping is: key = option string with all dash '-' character(s) at the beginning of the string removed. Internal dashes are maintained. value = list of all argument strings associated with the option string on the command line :param argv: (list) A list of command line arguments that maintain the argument order that was entered on command line cCst ||¡dSrn)rr&rpr$r$r%r&3szMultiDefinitions.__init__c Cs$i}t|ƒ}d}|D]Ü}d|dk}|dkrè|dkr:qòn®d|krŠ| d¡}|d d¡}|| ¡krz|| |d¡qè|dg||<n^||dkrè||d d¡sè| d¡}|| ¡krÖ|| ||d¡n||dg||<|d7}qi} | ¡D] } t|| ƒdkrþ|| | | <qþ| S)Nrr…TrNr†r)rrŽr‡r<Úappendr) r#r rr‘r’r“r”r•r–Z multi_mapÚkeyr$r$r%r6s4        z&MultiDefinitions._make_definitions_objN)rjrkrlrmr&rr$r$r$r%r sr)rmr Zcommandlines.exceptionsrrrÚobjectrror r~rrrŒrrr$r$r$r%Ús N`CFY