o 3gTR@sddlmZddlZddlZddlZddlmZmZddl m Z m Z ddl m Z ddlmZddlmZeeZejejZZGdd d eZGd d d eZGd d d eZGdddeZGdddeZGdddeZGdddeZGdddeZGdddZ          d;ddZ!dd Z"Gd!d"d"Z#Gd#d$d$e#Z$Gd%d&d&e#Z%Gd'd(d(Z&Gd)d*d*eZ'Gd+d,d,e'Z(Gd-d.d.e'Z)e)e*d/d0Z+Gd1d2d2Z,e,d3d4Z-e,d5d6Z.e,d7d8Z/e,d9d:Z0dS)<) annotationsN)ABCabstractmethod)Callable Generator)local)get_translation_for)getdocc@eZdZdZdS) SwitchErrorzFA general switch related-error (base class of all other switch errors)N__name__ __module__ __qualname____doc__rrL/home/garg/my-data/venv/lib/python3.10/site-packages/plumbum/cli/switches.pyr r c@r )PositionalArgumentsErrorzDRaised when an invalid number of positional arguments has been givenNr rrrrrrrc@r )SwitchCombinationErrorz=Raised when an invalid combination of switches has been givenNr rrrrrrrc@r ) UnknownSwitchz1Raised when an unrecognized switch has been givenNr rrrrrrrc@r )MissingArgumentzCRaised when a switch requires an argument, but one was not providedNr rrrrr!rrc@r )MissingMandatorySwitchz1Raised when a mandatory switch has not been givenNr rrrrr%rrc@r )WrongArgumentTypezjRaised when a switch expected an argument of some type, but an argument of a wrong type has been givenNr rrrrr)rrc@r )SubcommandErrorz5Raised when there's something wrong with sub-commandsNr rrrrr.rrc@seZdZddZdS) SwitchInfocKs"|D] \}}t|||qdSN)itemssetattr)selfkwargskvrrr__init__6szSwitchInfo.__init__N)r rrr#rrrrr5s rFrSwitchesc s^ttrgddDdd D ddD f dd} | S)a A decorator that exposes functions as command-line switches. Usage:: class MyApp(Application): @switch(["-l", "--log-to-file"], argtype = str) def log_to_file(self, filename): handler = logging.FileHandler(filename) logger.addHandler(handler) @switch(["--verbose"], excludes=["--terse"], requires=["--log-to-file"]) def set_debug(self): logger.setLevel(logging.DEBUG) @switch(["--terse"], excludes=["--verbose"], requires=["--log-to-file"]) def set_terse(self): logger.setLevel(logging.WARNING) :param names: The name(s) under which the function is reachable; it can be a string or a list of string, but at least one name is required. There's no need to prefix the name with ``-`` or ``--`` (this is added automatically), but it can be used for clarity. Single-letter names are prefixed by ``-``, while longer names are prefixed by ``--`` :param envname: Name of environment variable to extract value from, as alternative to argv :param argtype: If this function takes an argument, you need to specify its type. The default is ``None``, which means the function takes no argument. The type is more of a "validator" than a real type; it can be any callable object that raises a ``TypeError`` if the argument is invalid, or returns an appropriate value on success. If the user provides an invalid value, :func:`plumbum.cli.WrongArgumentType` :param argname: The name of the argument; if ``None``, the name will be inferred from the function's signature :param list: Whether or not this switch can be repeated (e.g. ``gcc -I/lib -I/usr/lib``). If ``False``, only a single occurrence of the switch is allowed; if ``True``, it may be repeated indefinitely. The occurrences are collected into a list, so the function is only called once with the collections. For instance, for ``gcc -I/lib -I/usr/lib``, the function will be called with ``["/lib", "/usr/lib"]``. :param mandatory: Whether or not this switch is mandatory; if a mandatory switch is not given, :class:`MissingMandatorySwitch ` is raised. The default is ``False``. :param requires: A list of switches that this switch depends on ("requires"). This means that it's invalid to invoke this switch without also invoking the required ones. In the example above, it's illegal to pass ``--verbose`` or ``--terse`` without also passing ``--log-to-file``. By default, this list is empty, which means the switch has no prerequisites. If an invalid combination is given, :class:`SwitchCombinationError ` is raised. Note that this list is made of the switch *names*; if a switch has more than a single name, any of its names will do. .. note:: There is no guarantee on the (topological) order in which the actual switch functions will be invoked, as the dependency graph might contain cycles. :param excludes: A list of switches that this switch forbids ("excludes"). This means that it's invalid to invoke this switch if any of the excluded ones are given. In the example above, it's illegal to pass ``--verbose`` along with ``--terse``, as it will result in a contradiction. By default, this list is empty, which means the switch has no prerequisites. If an invalid combination is given, :class:`SwitchCombinationError ` is raised. Note that this list is made of the switch *names*; if a switch has more than a single name, any of its names will do. :param help: The help message (description) for this switch; this description is used when ``--help`` is given. If ``None``, the function's docstring will be used. :param overridable: Whether or not the names of this switch are overridable by other switches. If ``False`` (the default), having another switch function with the same name(s) will cause an exception. If ``True``, this is silently ignored. :param group: The switch's *group*; this is a string that is used to group related switches together when ``--help`` is given. The default group is ``Switches``. :returns: The decorated function (with a ``_switch_info`` attribute) cSg|]}|dqS-lstrip.0nrrr zswitch..cSr%r&r(r*rrrr-r.cSr%r&r(r*rrrr-r.cs|durt|j}t|dkr|dntd}n}dur#t|n}|s+t|}t|  ||d |_|S)NVALUE) namesenvnameargtypelistfunc mandatory overridablegrouprequiresexcludesargnamehelp) inspectgetfullargspecargslen_r strr _switch_info)r6argspecargname2help2 r<r4r3r;r9r=r5r7r2r8r:rrdecos, zswitch..deco isinstancerC) r2r4r<r5r7r:r;r=r8r9r3rIrrHrswitch;s b rLcsfdd}|S)zA decorator that exposes a function as a switch, "inferring" the name of the switch from the function's name (converting to lower-case, and replacing underscores with hyphens). The arguments are the same as for :func:`switch `.cs$t|jddgRi|S)NrBr')rLr replacer6r@r rrrIs$zautoswitch..decor)r@r rIrrOr autoswitchsrPc@sFeZdZdZdZedZeddefddZdd Z d d Z d d Z dS) SwitchAttrab A switch that stores its result in an attribute (descriptor). Usage:: class MyApp(Application): logfile = SwitchAttr(["-f", "--log-file"], str) def main(self): if self.logfile: open(self.logfile, "w") :param names: The switch names :param argtype: The switch argument's (and attribute's) type :param default: The attribute's default value (``None``) :param argname: The switch argument's name (default is ``"VALUE"``) :param kwargs: Any of the keyword arguments accepted by :func:`switch ` __plumbum_switchattr_dict__r1NFc Ksd|_|r$|dur$td|}d|vr|d|7<n|d|d<t|f|||d||tg}|rU|durAg|_dSt|t|frO|||_dS|g|_dS||_dS)NzSets an attributez; the default is {0}r=z; )r4r<r5) rrBformatr)rLtype_default_valuerKtuple) rr2r4defaultr5r<r defaultmsglisttyperrrr#s    zSwitchAttr.__init__cCs|||dSr)__set__rinstvalrrr__call__szSwitchAttr.__call__cCs$|dur|St||ji||jSr)getattr ATTR_NAMEgetrU)rr\clsrrr__get__szSwitchAttr.__get__cCsF|durtdt||jst||j||idS|t||j|<dS)Nz cannot set an unbound SwitchAttr)AttributeErrorhasattrr`rr_r[rrrrZs  zSwitchAttr.__set__) r rrrr`rBr1rCr#r^rcrZrrrrrQs  rQc@"eZdZdZdddZddZdS) FlagabA specialized :class:`SwitchAttr ` for boolean flags. If the flag is not given, the value of this attribute is ``default``; if it is given, the value changes to ``not default``. Usage:: class MyApp(Application): verbose = Flag(["-v", "--verbose"], help = "If given, I'll be very talkative") :param names: The switch names :param default: The attribute's initial value (``False`` by default) :param kwargs: Any of the keyword arguments accepted by :func:`switch `, except for ``list`` and ``argtype``. FcKs tj||fd|dd|dS)NFr4rWr5)rQr#rr2rWr rrrr# s z Flag.__init__cCs|||j dSr)rZrU)rr\rrrr^%z Flag.__call__N)Fr rrrr#r^rrrrrgs rgc@rf) CountOfaLA specialized :class:`SwitchAttr ` that counts the number of occurrences of the switch in the command line. Usage:: class MyApp(Application): verbosity = CountOf(["-v", "--verbose"], help = "The more, the merrier") If ``-v -v -vv`` is given in the command-line, it will result in ``verbosity = 4``. :param names: The switch names :param default: The default value (0) :param kwargs: Any of the keyword arguments accepted by :func:`switch `, except for ``list`` and ``argtype``. rcKs&tj||fd|dd|||_dS)NTrh)rQr#rUrirrrr#8s zCountOf.__init__cCs||t|dSr)rZrA)rr\r"rrrr^>rjzCountOf.__call__N)rrkrrrrrl)s  rlc@s eZdZdZddZddZdS) positionalaY Runs a validator on the main function for a class. This should be used like this:: class MyApp(cli.Application): @cli.positional(cli.Range(1,10), cli.ExistingFile) def main(self, x, *f): # x is a range, f's are all ExistingFile's) Or, Python 3 only:: class MyApp(cli.Application): def main(self, x : cli.Range(1,10), *f : cli.ExistingFile): # x is a range, f's are all ExistingFile's) If you do not want to validate on the annotations, use this decorator ( even if empty) to override annotation validation. Validators should be callable, and should have a ``.choices()`` function with possible choices. (For future argument completion, for example) Default arguments do not go through the validator. #TODO: Check with MyPy cO||_||_dSr)r@kargs)rr@rorrrr#d zpositional.__init__c Cst|}t|jdd}dgt|}d}ttt|t|jD] }|j|||<q#t|dt|jkr=|jd}|jD]\}}||j krN|}qB||| |<qB||_ ||_ |S)Nr0) r>r?r5r@rArangeminrorvarargsindexrmpositional_varargs) rfunctionm args_namespositional_listrtiitemvaluerrrr^hs   zpositional.__call__NrkrrrrrmGs rmc@s.eZdZdZeddZd ddZddZd S) ValidatorrcCsdS)z+Must be implemented for a Validator to workNrrobjrrrr^szValidator.__call__cCtS)zFShould return set of valid choices, can be given optional partial infosetrpartialrrrchoicesszValidator.choicescCsli}|jD]}t|ddD]}|ddkrt||||<q qdd|D}d|}|jjd|d S) z/If not overridden, will print the slots as args __slots__rrrBcss"|] \}}|d|VqdS)z = Nr)r+namer}rrr s z%Validator.__repr__.., ())__mro__r_rjoin __class__r )rslotsrbpropmystrs mystrs_strrrr__repr__s   zValidator.__repr__Nr)r rrrrr^rrrrrrr~s    r~c@s6eZdZdZdZddZddZddZd d d Zd S)Rangea  A switch-type validator that checks for the inclusion of a value in a certain range. Usage:: class MyApp(Application): age = SwitchAttr(["--age"], Range(18, 120)) :param start: The minimal value :param end: The maximal value startendcCrnrr)rrrrrrr#rpzRange.__init__cCsd|jdd|jddS)N[dz..]rrrrrrszRange.__repr__cCs8t|}||jks||jkrttd|j|j|S)NzNot in range [{0:d}..{1:d}])intrr ValueErrorrBrSrrrrr^s zRange.__call__rcCstt|j|jdS)Nr0)rrrrrrrrrrsz Range.choicesNr) r rrrrr#rr^rrrrrrs rc@sReZdZdZddedd ddZddZ d!d"ddZd!d#ddZd$ddZ dS)%Seta A switch-type validator that checks that the value is contained in a defined set of values. Usage:: class MyApp(Application): mode = SwitchAttr(["--mode"], Set("TCP", "UDP", case_sensitive = False)) num = SwitchAttr(["--num"], Set("MIN", "MAX", int, csv = True)) :param values: The set of values (strings), or other callable validators, or types, or any other object that can be compared to a string. :param case_sensitive: A keyword argument that indicates whether to use case-sensitive comparison or not. The default is ``False`` :param csv: splits the input as a comma-separated-value before validating and returning a list. Accepts ``True``, ``False``, or a string for the separator :param all_markers: When a user inputs any value from this set, all values are iterated over. Something like {"*", "all"} would be a potential setting for this option. F)case_sensitivecsv all_markersvaluesstr | Callable[[str], str]rboolr bool | strrcollections.abc.Set[str]returnNonecGs6||_t|tr|r dnd|_n||_||_||_dS)N,r)rrKrrrr)rrrrrrrrr#s   z Set.__init__cCs"ddd|jD}d|dS)Nrcss$|] }t|tr |n|jVqdSr)rKrCr )r+r"rrrrs"zSet.__repr__..{})rr)rrrrrrs z Set.__repr__Tr}rC check_csvGenerator[str, None, None]c cs|jr|r||jD]}|j|ddEdHq |js"|}|jD]5}t|tr@|js3|}||ks<||j vr?|Vq%t t  ||VWdn1sUwYq%dS)NF)r) rsplit _call_iterstriprlowerrrKrCr contextlibsuppressr)rr}rr"optrrrrs$     zSet._call_iterstr | list[str]cCsRt|||}|sd|d|jd}t||jr|s#t|dkr%|S|dS)NzInvalid value: z (Expected one of rr0r)r5rrrrrA)rr}rrmsgrrrr^sz Set.__call__rcs4dd|jD}||jO}rfdd|DS|S)NcSs&h|]}t|tr |nd|dqS)rrrJr+rrrr s&zSet.choices..csh|] }|r|qSr)r startswithrrrrrs)rr)rrrrrrrs  z Set.choicesN) rrrrrrrrrr)T)r}rCrrrr)r}rCrrrrr) r rrr frozensetr#rrr^rrrrrrs  rT)rc@s2eZdZdZddZddZddZd d d Zd S) Predicatez=A wrapper for a single-argument function with pretty printingcCs ||_dSrrN)rr6rrrr# zPredicate.__init__cCs|jjSr)r6r rrrr__str__szPredicate.__str__cCs ||SrrN)rr]rrrr^rzPredicate.__call__rcCrrrrrrrrszPredicate.choicesNr)r rrrr#rr^rrrrrrs rcC(t|}|sttd||S)zUA switch-type validator that ensures that the given argument is an existing directoryz{0} is not a directory)rpathis_dirrrBrSr]prrrExistingDirectory rcCs4t|}|rt|d|s||S)Nz1 is a file, should be nonexistent, or a directory)rris_filerexistsmkdirrrrr MakeDirectory(s rcCr)zPA switch-type validator that ensures that the given argument is an existing filez{0} is not a file)rrrrrBrSrrrr ExistingFile2rrcCs(t|}|rttd||S)zRA switch-type validator that ensures that the given argument is a nonexistent pathz{0} already exists)rrrrrBrSrrrrNonexistentPath;rr) NNFFrrNFr$N)1 __future__rcollections.abc collectionsrr>abcrrtypingrrplumbumrplumbum.cli.i18nr plumbum.libr r _translationgettextngettextrB Exceptionr rrrrrrrrrLrPrQrgrlrmr~rrrCCSVrrrrrrrrrsd     E:" L