U 6e-U @sdZddlZddlmZmZmZddlmZddlm Z ddl m Z m Z m Z mZmZmZmZddlmZddlmZmZmZmZmZmZmZdd lmZmZdd lm Z dd l!m"Z"m#Z#d d ddgZ$Gddde Z%e%j&fe ee%eedddZ'ee e(e fdddZ)e%j&fe e%dddd Z*ee+ddddZ,eeeee+eedddZ-d)ee(e(e+dd d!Z.e%j&dddfeee e%ee(ee e(e fee e(e fdd"d#d Z/e ee(e0fd$d%d&Z1ee(ee dd'd(dZ2dS)*z^ Assembling ~~~~~~~~~~ Functions and classes to properly assemble your commands in a parser. N)OPTIONAL ZERO_OR_MOREArgumentParser) OrderedDict)Enum)AnyCallableDictIteratorListOptionalTuple)COMPLETION_ENABLED) ATTR_ALIASES ATTR_ARGSATTR_EXPECTS_NAMESPACE_OBJECT ATTR_NAMEDEFAULT_ARGUMENT_TEMPLATE DEST_FUNCTIONPARSER_FORMATTER) NotDefinedParserAddArgumentSpec)AssemblingError) get_arg_specget_subparsersset_default_command add_commandsadd_subcommandsNameMappingPolicyc@seZdZdZdZdZdS)ra: Represents possible approaches to treat default values when inferring argument specification from function signature. * `BY_NAME_IF_KWONLY` is the default and recommended approach introduced in v0.30. It enables fine control over two aspects: * positional vs named; * required vs optional. "Normal" arguments are identified by position, "kwonly" are identified by name, regardless of the presence of default values. A positional with a default value becomes optional but still positional (``nargs=OPTIONAL``). A kwonly argument without a default value becomes a required named argument. Example:: def func(alpha, beta=1, *, gamma, delta=2): ... is equivalent to:: prog alpha [beta] --gamma [--delta DELTA] That is, ``alpha`` and ``--gamma`` are mandatory while ``beta`` and ``--delta`` are optional (they have default values). * `BY_NAME_IF_HAS_DEFAULT` is very close to the the legacy approach (pre-v0.30). If a function argument has a default value, it becomes an "option" (called by name, like ``--foo``); otherwise it's treated as a positional argument. Example:: def func(alpha, beta=1, *, gamma, delta=2): ... is equivalent to:: prog [--beta BETA] [--delta DELTA] alpha gamma That is, ``alpha`` and ``gamma`` are mandatory and positional, while ``--beta`` and ``--delta`` are optional (they have default values). Note that it's impossible to have an optional positional or a mandatory named argument. The difference between this policy and the behaviour of Argh before v0.30 is in the treatment of kwonly arguments without default values: they used to become ``--foo FOO`` (required) but for the sake of simplicity they are treated as positionals. If you are already using kwonly args, please consider the better suited policy `BY_NAME_IF_KWONLY` instead. It is recommended to migrate any older code to `BY_NAME_IF_KWONLY`. .. versionadded:: 0.30 z6specify CLI argument by name if it has a default valuez4specify CLI argument by name if it comes from kwonlyN)__name__ __module__ __qualname____doc__ZBY_NAME_IF_HAS_DEFAULTBY_NAME_IF_KWONLYr$r$.lib/python3.8/site-packages/argh/assembling.pyr,s9)functionname_mapping_policyreturnc #st|tdrdS|tkr&td|t|}ttt|jt|j pFt }t t ||j }dd|Dtfddt Dt fddDtttttfdfd d }|jD]T}||\}}||t} t||| d } | tkr|tjkrt| _n|| _| Vq|j D]~}||\}}|jrR||jkrR|j|} nt} t||| d } |tjkr|| _| tkrd | _n| tkr|| _| Vq"|jrt|j|jd dgtdVdS)NFzUnknown name mapping policy cSsg|] }|dqS)rr$).0ar$r$r% sz0infer_argspecs_from_function..c3s|]}||fVqdSN)countr)char)named_arg_charsr$r% sz/infer_argspecs_from_function..c3s|]}d|kr|VqdS)Nr$r.)named_arg_char_countsr$r%r1s )r(csP|dd}|g}|dk}|r._make_cli_arg_names_options) func_arg_name cli_arg_names default_valueTr4r5)r<r=nargs)getattrrrNotImplementedErrorrdictzipreversedargsdefaultstuplesetlistZ kwonlyargsr r strgetrrr#rr?r=ZkwonlydefaultsZ is_requiredZvarargsr6r) r&r' func_specZdefault_by_arg_nameZ named_argsr;r7Zcli_arg_names_positionalZcli_arg_names_optionsr>Zarg_specr$)r:r3r0r%infer_argspecs_from_functionjsr   "          rM)parser_add_argument_specr(cCs|j}i}|jdd }d}|j}|dtfkrt|tr`|s|ddkr|rVdnd|d<n*|ddkr|dd |krt||d<|d rdt |t |krt|d d|d<|S) u Given an argument specification, returns types, actions, etc. that could be guessed from it: * ``default=3`` → ``type=int`` TODO: deprecate in favour of ``foo: int = 3`` in func signature. * ``choices=[3]`` → ``type=int`` TODO: deprecate in favour of ``foo: int`` in func signature. * ``type=bool`` → ``action="store_false"`` or ``action="store_true"`` (if action was not explicitly defined). rr5)storeappendNaction store_false store_truetyperOchoices) other_add_parser_kwargsr= startswithr>r isinstanceboolrKrTrI)rNrVZguessedZ is_positionalZTYPE_AWARE_ACTIONSr>r$r$r%+guess_extra_parser_add_argument_spec_kwargss"   rZc Cspt|}t|j}t|tg}tt||d}|rJ|sJ|sJt|jd|sT|}nTzt |||d}Wn@tk r}z"t |t|jd||W5d}~XYnX|D]} t | |j dz|j | j| } WnTtk r(}z4d| j} t|jd| jd | d||W5d}~XYnXtr| jr| j| _qt|} | r\|js\| |_|jft|idS) a Sets default command (i.e. a function) for given parser. If `parser.description` is empty and the function has a docstring, it is used as the description. :param function: The function to use as the command. :name_mapping_policy: The policy to use when mapping function arguments onto CLI arguments. See :class:`.NameMappingPolicy`. .. versionadded:: 0.30 .. note:: If there are both explicitly declared arguments (e.g. via :func:`~argh.decorators.arg`) and ones inferred from the function signature, declared ones will be merged into inferred ones. If an argument does not conform to the function signature, `AssemblingError` is raised. .. note:: If the parser was created with ``add_help=True`` (which is by default), option name ``-h`` is silently removed from any argument. r'zW: cannot extend argument declarations for an endpoint function that takes no arguments.) inferred_args declared_args has_varkwz: Nspecparser_adds_help_arg/z: cannot add 'z' as )rrYZvarkwr@rrIrMrr!_merge_inferred_and_declared_argsprint _extend_parser_add_argument_specadd_help add_argumentr=Zget_all_kwargs Exceptionjoinr<rZ completerinspectZgetdoc description set_defaultsr) parserr&r'rLr^r]r\Zparser_add_argument_specsexcr`rQZ err_cli_argsZ docstringr$r$r%rs`$      (    )r`rar(cCsL|jt|d|jkr(|jjtd|rHd|jkrHdd|jD|_dS)Nhelpro-hcSsg|]}|dkr|qS)rqr$)r)namer$r$r%r+nsz4_extend_parser_add_argument_spec..)rVupdaterZrr=r_r$r$r%re]s re)r\r]r^r(c st|D]}||j<q |D]}|}|j}|krt|j}t|j}||krddd}||} ||} td|d| d| d||q|r||<qfdd D} d |j} d d d | D} td | d | qtS)NZ positionalZoptional)TFz argument "z" declared as z (in function signature) and z (via decorator). If you've just migrated from Argh v.0.29, please check the new default NameMappingPolicy. Perhaps you need to replace `func(x=1)` with `func(*, x=1)`?c3s|]}|jVqdSr,)r=r)xZspecs_by_func_arg_namer$r%r1sz4_merge_inferred_and_declared_args..z, css|]}d|VqdS)rbN)rirtr$r$r%r1sz argument z" does not fit function signature: ) rr<_is_positionalr=rrsrirIvalues)r\r]r^rNZ declared_specr<Zdecl_positionalZinfr_positionalZkindsZ kind_inferredZ kind_declaredZdest_option_stringsZ msg_flagsZ msg_signaturer$rvr%rcqsB      rcr5)rE prefix_charsr(cCs2|r |dstd|ddt|r.dSdS)NrzExpected at least one argumentFT) ValueErrorrWrG)rEryr$r$r%rws  rw)rm functionsr' group_name group_kwargs func_kwargsr(c Cs|pi}t|dd}|r:|j||dd}|jf|}n |rFtd|D]:}t|\} } |rh| ||j| f| } t| ||dqJdS)a Adds given functions as commands to given parser. :param parser: an :class:`argparse.ArgumentParser` instance. :param functions: a list of functions. A subparser is created for each of them. If the function is decorated with :func:`~argh.decorators.arg`, the arguments are passed to :meth:`argparse.ArgumentParser.add_argument`. See also :func:`~argh.dispatching.dispatch` for requirements concerning function signatures. The command name is inferred from the function name. Note that the underscores in the name are replaced with hyphens, i.e. function name "foo_bar" becomes command name "foo-bar". :param name_mapping_policy: See :class:`argh.assembling.NameMappingPolicy`. .. versionadded:: 0.30 :param group_name: an optional string representing the group of commands. For example, if a command named "hello" is added without the group name, it will be available as "prog.py hello"; if the group name if specified as "greet", then the command will be accessible as "prog.py greet hello". The group itself is not callable, so "prog.py greet" will fail and only display a help message. :param func_kwargs: a `dict` of keyword arguments to be passed to each nested ArgumentParser instance created per command (i.e. per function). Members of this dictionary have the highest priority, so a function's docstring is overridden by a `help` in `func_kwargs` (if present). :param group_kwargs: a `dict` of keyword arguments to be passed to the nested ArgumentParser instance under given `group_name`. .. note:: This function modifies the parser object. Generally side effects are bad practice but we don't seem to have any choice as ArgumentParser is pretty opaque. You may prefer :meth:`~argh.helpers.ArghParser.add_commands` for a bit more predictable API. .. note:: An attempt to add commands to a parser which already has a default function (e.g. added with :func:`~argh.assembling.set_default_command`) results in `AssemblingError`. T)Zcreatetitlerpz2`group_kwargs` only makes sense with `group_name`.r[N)r add_parserrKadd_subparsersrz_extract_command_meta_from_funcrsr) rmr{r'r|r}r~Zsubparsers_actionZ subsubparserfunccmd_namefunc_parser_kwargsZcommand_parserr$r$r%rs(C   )rr(cCs:t|t|jdd}|jtd}t|tg|d<||fS)Nr4r5)roformatter_classaliases)r@rrr6r"rr)rrrr$r$r%r/s r)rmr|r{r(cKst||||ddS)a A wrapper for :func:`add_commands`. These examples are equivalent:: add_commands( parser, [get, put], group_name="db", group_kwargs={ "title": "database commands", "help": "CRUD for our silly database" } ) add_subcommands( parser, "db", [get, put], title="database commands", help="CRUD for our database" ) )r|r}N)r)rmr|r{r}r$r$r%r@s)r5)3r"rjargparserrr collectionsrenumrtypingrrr r r r r Zargh.completionrZargh.constantsrrrrrrrZargh.dtorrZargh.exceptionsrZ argh.utilsrr__all__rr#rMrJrZrrYrercrwrrBrrr$r$r$r% s|  $ $  B a 5 b  Q  e