U des @sJdZddlZddlZddlZddlmZmZmZddlm Z ddl m Z ddl m Z mZmZmZmZmZmZmZmZmZmZzddlmZeegZWnek regZYnXddlmZdd lmZm Z m!Z!m"Z"m#Z#m$Z$dd l%m&Z&m'Z'dd l(m)Z)dd l*m+Z+d dddgZ,Gddde Z-d0eee-e.ee'dddZ/e'ee0e fdddZ1d1eee-dddd Z2e'e.ddddZ3ee'ee'e.ee'ddd Z4d2ee0e0e.d"d#d$Z5d3eeeee-ee0eee0e feee0e fdd%d&dZ6eee0e7fd'd(d)Z8ee0eedd*d+dZ9Gd,d-d-e)Z:Gd.d/d/Z;dS)4z^ Assembling ~~~~~~~~~~ Functions and classes to properly assemble your commands in a parser. N)OPTIONAL ZERO_OR_MOREArgumentParser) OrderedDict)Enum) AnyCallableDictIteratorListLiteralOptionalTupleUnionget_args get_origin) UnionType)COMPLETION_ENABLED) ATTR_ALIASES ATTR_ARGS ATTR_NAMEDEFAULT_ARGUMENT_TEMPLATE DEST_FUNCTIONPARSER_FORMATTER) NotDefinedParserAddArgumentSpec)AssemblingError)get_subparsersset_default_command add_commandsadd_subcommandsNameMappingPolicyc@seZdZdZdZdZdS)r!a: 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__BY_NAME_IF_HAS_DEFAULTZBY_NAME_IF_KWONLYr'r'.lib/python3.8/site-packages/argh/assembling.pyr!As9F)functionname_mapping_policy can_use_hintsreturnc#s|r|tkrtd|t|}tdd|jD}dd|jD}dd|DtfddtDt fddDt t t t t fd fd d }|jD]}||j \}} |j|jk r|j} nt} i} |r|j} |j | krt| |j } |j|j|jfkr| tkrx|sxtd |j d |jd} |rdt| tt| tj}t |j || | d}| tkr|tjkr| |_!nt"|_#|rd|j$kr|j$%d}|dkrt"|_#|tjkrt&|j't(r|j$)dt(kr|j$d=|Vq|j|j*krt |j || | d}|tjkrV| tkrl| |_!n| |_!| tkrld|_+|rt&|j't(r|j$)dt(kr|j$d=|Vq|j|j,krt |j |j -ddgt.| dVqdS)NzUnknown name mapping policy css|]}|j|jkVqdSN)kind KEYWORD_ONLY.0pr'r'r( sz/infer_argspecs_from_function..cSs*g|]"}|j|jk s |j|jkr|jqSr')defaultemptyr.r/namer0r'r'r( s z0infer_argspecs_from_function..cSsg|] }|dqS)rr')r1ar'r'r(r7sc3s|]}||fVqdSr-)countr1char)named_arg_charsr'r(r3sc3s|]}d|kr|VqdS)Nr'r:)named_arg_char_countsr'r(r3s r,csP|dd}|g}|dk}|r._make_cli_arg_names_optionsz Argument "z" in function "a" is not keyword-only but has a default value. Please note that since Argh v.0.30 the default name mapping policy has changed. More information: https://argh.readthedocs.io/en/latest/changes.html#version-0-30-0-2023-10-21 You need to upgrade your functions so that the arguments that have default values become keyword-only: f(x=1) -> f(*, x=1) If you actually want an optional positional argument, please set the name mapping policy explicitly to `BY_NAME_IF_KWONLY`. If you choose to postpone the migration, you have two options: a) set the policy explicitly to `BY_NAME_IF_HAS_DEFAULT`; b) pin Argh version to 0.29 until you are ready to migrate. Thank you for understanding! ) func_arg_name cli_arg_names default_valueother_add_parser_kwargsrequiredFtypeTr@rA)rGrHnargsrJ)/r!NotImplementedErrorinspect signatureany parametersvaluesdictsettuplerr strr6r4r5r__annotations__TypingHintArgSpecGuessertyping_hint_to_arg_spec_paramsr.ZPOSITIONAL_ONLYZPOSITIONAL_OR_KEYWORDtextwrapdedentr"stripArgumentNameMappingErrorwarningswarnDeprecationWarningr&rrHrrMrJpop isinstancerIboolgetr/Z is_requiredZVAR_POSITIONALrBr)r)r*r+func_signatureZ has_kwonlyZ named_argsrFZ parameterZcli_arg_names_positionalZcli_arg_names_optionsrIZextra_spec_kwargsZhintsmessageZarg_specvaluer')rEr>r<r(infer_argspecs_from_functions    "   #            ri)parser_add_argument_specr,cCs|j}i}|jdd }d}|j}|dtfkrt|tr`|s|ddkr|rVdnd|d<nJ|ddkrt|tt frd |krt |d <n|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). rrA)storeappendNaction store_false store_truerLrMrkchoices) rJrH startswithrIrrcrdrelistrVrrL)rjrJZguessed is_positionalZTYPE_AWARE_ACTIONSrIr'r'r(+guess_extra_parser_add_argument_spec_kwargs6s(    rt)r)r*r,c Cst|}tdd|jD}t|tg}| }tt|||d}|rb|sb|sbt |j d|sl|}nLzt |||d}Wn8t k r} zt |j d| | W5d} ~ XYnX|D]} t | |j dz|j| j| } WnTtk r8} z4d | j} t|j d | jd | d| | W5d} ~ XYnXtr| jr| j| _qt|} | rl|jsl| |_|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`. If not defined explicitly, :meth:`.NameMappingPolicy.BY_NAME_IF_KWONLY` is used. .. versionadded:: 0.30 .. versionchanged:: 0.30.2 Raises `ArgumentNameMappingError` if the policy was not explicitly defined and a non-kwonly argument has a default value. The reason is that it's very likely to be a case of non-migrated code where the argument was intended to be mapped onto a CLI option. It's better to fail explicitly than to silently change the CLI API. .. 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, `ArgumentNameMappingError` 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. css|]}|j|jkVqdSr-)r.Z VAR_KEYWORDr0r'r'r(r3sz&set_default_command..)r*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 )rOrPrQrRrSgetattrrrrrir^r"!_merge_inferred_and_declared_args _extend_parser_add_argument_specadd_help add_argumentrHZget_all_kwargs ExceptionjoinrrGrZ completerZgetdoc description set_defaultsr)parserr)r*rfrwrvr+ruZparser_add_argument_specsexcryrmZ err_cli_argsZ docstringr'r'r(rnsh,     (    )ryrzr,cCsL|jt|d|jkr(|jjtd|rHd|jkrHdd|jD|_dS)Nhelpr-hcSsg|]}|dkr|qS)rr')r1r6r'r'r(r7sz4_extend_parser_add_argument_spec..)rJupdatertrrHrxr'r'r(r~s r~)rurvrwr,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-)rHr1xZspecs_by_func_arg_namer'r(r36sz4_merge_inferred_and_declared_args..z, css|]}d|VqdS)r{N)rrr'r'r(r3;sz argument z" does not fit function signature: ) rrG_is_positionalrHr^rrrrrS)rurvrwrjZ declared_specrGZdecl_positionalZinfr_positionalZkindsZ kind_inferredZ kind_declaredZdest_option_stringsZ msg_flagsZ msg_signaturer'rr(r}sB      r}rA)args prefix_charsr,cCs2|r |dstd|ddt|r.dSdS)NrzExpected at least one argumentFT) ValueErrorrqrV)rrr'r'r(rEs  r)r 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)Zcreatetitlerz2`group_kwargs` only makes sense with `group_name`.)r*N)r add_parserreadd_subparsersr_extract_command_meta_from_funcrr) rrr*rrrZsubparsers_actionZ subsubparserfunccmd_namefunc_parser_kwargsZcommand_parserr'r'r(rMs(C   )rr,cCs:t|t|jdd}|jtd}t|tg|d<||fS)Nr@rA)rformatter_classaliases)r|rr"rBr%rr)rrrr'r'r(rs r)rrrr,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" ) )rrN)r)rrrrr'r'r(r sc@s eZdZdS)r^N)r"r#r$r'r'r'r(r^sr^c@sNeZdZeeeefZed e ee ee fdddZ ee e dddZdS) rYF)type_defrsr,cs t|t|}||jkr"d|iS|tkr2dtiStkrL|t|ddStfddtDri}|d}||jkr||d<|tkrt|d<t|tkrt|d<| |}|r||d<td|krd|d<|Stkri}t|d<|d|jkr|d|d<|SiS) NrLrMr)rprLc3s|]}|kVqdSr-r')r1toriginr'r(r3szJTypingHintArgSpecGuesser.typing_hint_to_arg_spec_params..FrK) rr BASIC_TYPESrrrr rLrQ UNION_TYPES!_extract_item_type_from_list_type)clsrrsrZretvalZ first_subtypeZ item_typer'rr(rZs@       z7TypingHintArgSpecGuesser.typing_hint_to_arg_spec_paramsr?cCs"t|}|d|jkr|dSdS)Nr)rr)rrrr'r'r(rsz:TypingHintArgSpecGuesser._extract_item_type_from_list_typeN)F)r"r#r$rWintfloatrdr classmethodrLr rrZr rr'r'r'r(rYs  3rY)NF)N)rA)NNNN) s  4       @ 9 ; s  Q  e