f&~dZddlZddlZddlmZddlmZddlmZddl m Z ejdZ eGdd ejZGd d ejZd Zd ZdZGddeZGddeZGddeZGddeZGddeZGddeZGddeZgdZy)a A decorator-based method of constructing IPython magics with `argparse` option handling. New magic functions can be defined like so:: from IPython.core.magic_arguments import (argument, magic_arguments, parse_argstring) @magic_arguments() @argument('-o', '--option', help='An optional argument.') @argument('arg', type=int, help='An integer positional argument.') def magic_cool(self, arg): """ A really cool magic command. """ args = parse_argstring(magic_cool, arg) ... The `@magic_arguments` decorator marks the function as having argparse arguments. The `@argument` decorator adds an argument using the same syntax as argparse's `add_argument()` method. More sophisticated uses may also require the `@argument_group` or `@kwds` decorator to customize the formatting and the parsing. Help text for the magic is automatically generated from the docstring and the arguments:: In[1]: %cool? %cool [-o OPTION] arg A really cool magic command. positional arguments: arg An integer positional argument. optional arguments: -o OPTION, --option OPTION An optional argument. Here is an elaborated example that uses default parameters in `argument` and calls the `args` in the cell magic:: from IPython.core.magic import register_cell_magic from IPython.core.magic_arguments import (argument, magic_arguments, parse_argstring) @magic_arguments() @argument( "--option", "-o", help=("Add an option here"), ) @argument( "--style", "-s", default="foo", help=("Add some style arguments"), ) @register_cell_magic def my_cell_magic(line, cell): args = parse_argstring(my_cell_magic, line) print(f"{args.option=}") print(f"{args.style=}") print(f"{cell=}") In a jupyter notebook, this cell magic can be executed like this:: %%my_cell_magic -o Hello print("bar") i = 42 Inheritance diagram: .. inheritance-diagram:: IPython.core.magic_arguments :parts: 3 N UsageError)undoc) arg_split)dedentz[a-zA-Z][a-zA-Z0-9_-]*$c0eZdZdZdZdZdfd ZxZS)MagicHelpFormatterz@A HelpFormatter with a couple of changes to meet our needs. cXtjj|t|||SN)argparseRawDescriptionHelpFormatter _fill_textr)selftextwidthindents W/var/www/cvtools/html/venv/lib/python3.12/site-packages/IPython/core/magic_arguments.pyrzMagicHelpFormatter._fill_textes%33>>tVD\SXZ`aac|js&|j||jd\}|Sg}|jdk(r|j |jnm|jj }|j ||}tj|sd|z}|jD]}|j|d|dj|S)Nrz<%s> z, ) option_strings_metavar_formatterdestnargsextendupper _format_argsNAME_REmatchappendjoin)ractionmetavarpartsdefault args_string option_strings r_format_action_invocationz,MagicHelpFormatter._format_action_invocationis$$Ct..vv{{CAFHGNE||q  V223 !++++-"//@ }}[1"(;"6K%+%:%:IMLLM;!GHI99U# #rc2tt| ||||yr )superr add_usage)rusageactionsgroupsprefix __class__s rr,zMagicHelpFormatter.add_usages  $1%&&Qr)z:: %)__name__ __module__ __qualname____doc__rr)r, __classcell__r1s@rr r `sb$:RRrr c DeZdZdZdddddeddddf fd ZdZdZxZS) MagicArgumentParserz: An ArgumentParser tweaked for use by IPython magics. N-errorFc H|g}tt| ||||||||| |  y)N) progr- descriptionepilogparentsformatter_class prefix_charsargument_defaultconflict_handleradd_help)r+r9__init__) rr=r-r>r?r@rArBrCrDrEr1s rrFzMagicArgumentParser.__init__s> ?G !41t5#F_%8H- 2 Brct|)z5 Raise a catchable error instead of exiting. r)rmessages rr;zMagicArgumentParser.errors!!rc:t|}|j|S)zL Split a string into an argument list and parse that argument list. )r parse_args)r argstringargvs rparse_argstringz#MagicArgumentParser.parse_argstrings#t$$r) r2r3r4r5r rFr;rMr6r7s@rr9r9s8!!3!"&")B&" %rr9ct|di}d|vrt|dd|d<t|}t|fi|}d}|jdddD]}|j ||}||}|j |_|S)zB Construct an argument parser using the function decorations. argcmd_kwdsr>r5N)getattr real_namer9 decorators add_to_parser format_helpr5) magic_funckwdsarg_nameparsergroupdecoresults rconstruct_parserr]s :}b 1DD %j)TB]$H  2T 2F E%%dd+##FE2  E  ++-J Mrc8|jj|S)zA Parse the string of arguments for the given magic function. )rYrM)rVrKs rrMrMs    , ,Y 77rcr|j}|jdr|tdd}t|d|S)z& Find the real name of the magic. magic_N argcmd_name)r2 startswithlenrQ)rV magic_names rrRrRs<$$JX&H / :}j 99rceZdZdZdZdZy) ArgDecoratorzN Base class for decorators to add ArgumentParser information to a method. crt|ddsd|_g|_|jj||SN has_argumentsFT)rQrirSr!rfuncs r__call__zArgDecorator.__call__s4t_e4!%D  DO t$ rcy)zD Add this object's information to the parser, if necessary. NrrYrZs rrTzArgDecorator.add_to_parsers rN)r2r3r4r5rlrTrnrrrfrfs rrfceZdZdZddZdZy)magic_argumentszS Mark the magic as having argparse arguments and possibly adjust the name. Nc||_yr )name)rrss rrFzmagic_arguments.__init__  rct|ddsd|_g|_|j|j|_t ||_|Srh)rQrirSrsrar]rYrjs rrlzmagic_arguments.__call__sFt_e4!%D  DO 99 #yyD 't,  rr )r2r3r4r5rFrlrnrrrqrqs rrqc(eZdZUdZeed<dZdZy)ArgMethodWrapperz Base class to define a wrapper for ArgumentParser method. Child class must define either `_method_name` or `add_to_parser`. _method_namec ||_||_yr )argsrW)rrzrWs rrFzArgMethodWrapper.__init__s  rcl||}t||j|ji|jy)6 Add this object's information to the parser. N)rQrxrzrWros rrTzArgMethodWrapper.add_to_parsers6  F*))*DIICCrN)r2r3r4r5str__annotations__rFrTrnrrrwrwsrrwceZdZdZdZy)argumentzt Store arguments and keywords to pass to add_argument(). Instances also serve to decorate command methods. add_argumentNr2r3r4r5rxrnrrrr "LrrceZdZdZdZy)defaultszt Store arguments and keywords to pass to set_defaults(). Instances also serve to decorate command methods. set_defaultsNrrnrrrrrrrceZdZdZdZy)argument_groupzz Store arguments and keywords to pass to add_argument_group(). Instances also serve to decorate command methods. cN|j|ji|jS)r|)add_argument_grouprzrWros rrTzargument_group.add_to_parser#s$)v(($))AtyyAArN)r2r3r4r5rTrnrrrrs  Brrc(eZdZdZdZfdZxZS)rWz; Provide other keywords to the sub-parser constructor. c ||_yr )rW)rrWs rrFz kwds.__init__,rtrcPtt| |}|j|_|Sr )r+rWrlrO)rrkr1s rrlz kwds.__call__/s%T4)$/99 r)r2r3r4r5rFrlr6r7s@rrWrW)srrW)rqrrrWrM)r5r reIPython.core.errorrIPython.utils.decoratorsrIPython.utils.processrIPython.utils.textrcompilerr r ArgumentParserr9r]rMrRobjectrfrqrwrrrrW__all__rnrrrsLh **+% "**/ 0&R==&R&RP%(11%D,8 : 6 "l(|0"""" B% B <  r