o ˷e&@s dZddlZddlZddlmZddlmZddlmZddl m Z e dZ eGdd d ej ZGd d d ejZd d ZddZddZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZGdddeZgd ZdS)!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_-]*$cs2eZdZdZddZddZd fdd ZZS) MagicHelpFormatterz@A HelpFormatter with a couple of changes to meet our needs. cCstj|t|||SN)argparseRawDescriptionHelpFormatter _fill_textr)selftextwidthindentrS/var/www/ideatree/venv/lib/python3.10/site-packages/IPython/core/magic_arguments.pyr eszMagicHelpFormatter._fill_textcCs|js|||jd\}|Sg}|jdkr||jn#|j}|||}t|s1d|}|jD] }| d||fq4d |S)Nrz<%s>z%s %sz, ) option_strings_metavar_formatterdestnargsextendupper _format_argsNAME_REmatchappendjoin)r actionmetavarpartsdefault args_string option_stringrrr_format_action_invocationis      z,MagicHelpFormatter._format_action_invocation:: %cstt|||||dSr)superr add_usage)r usageactionsgroupsprefix __class__rrr'szMagicHelpFormatter.add_usage)r%)__name__ __module__ __qualname____doc__r r$r' __classcell__rrr,rr`s rc sFeZdZdZdddddeddddf fdd Zdd Zd d ZZS) MagicArgumentParserz: An ArgumentParser tweaked for use by IPython magics. N-errorFc s4|durg}tt|j||||||||| | d dS)N) progr( descriptionepilogparentsformatter_class prefix_charsargument_defaultconflict_handleradd_help)r&r3__init__) r r6r(r7r8r9r:r;r<r=r>r,rrr?s  zMagicArgumentParser.__init__cCst|)z5 Raise a catchable error instead of exiting. r)r messagerrrr5szMagicArgumentParser.errorcCst|}||S)zL Split a string into an argument list and parse that argument list. )r parse_args)r argstringargvrrrparse_argstrings z#MagicArgumentParser.parse_argstring) r.r/r0r1rr?r5rDr2rrr,rr3sr3cCs|t|di}d|vrt|dd|d<t|}t|fi|}d}|jdddD]}|||}|dur6|}q(||_|S)zB Construct an argument parser using the function decorations. argcmd_kwdsr7r1N)getattr real_namer3 decorators add_to_parser format_helpr1) magic_funckwdsarg_nameparsergroupdecoresultrrrconstruct_parsers   rScCs |j|S)zA Parse the string of arguments for the given magic function. )rOrD)rLrBrrrrDs rDcCs,|j}|dr|tdd}t|d|S)z& Find the real name of the magic. magic_N argcmd_name)r. startswithlenrG)rL magic_namerrrrHs  rHc@s eZdZdZddZddZdS) ArgDecoratorzN Base class for decorators to add ArgumentParser information to a method. cCs(t|dds d|_g|_|j||SN has_argumentsFT)rGr[rIrr funcrrr__call__s  zArgDecorator.__call__cCsdS)zD Add this object's information to the parser, if necessary. Nrr rOrPrrrrJszArgDecorator.add_to_parserN)r.r/r0r1r^rJrrrrrYs rYc@s"eZdZdZdddZddZdS)magic_argumentszS Mark the magic as having argparse arguments and possibly adjust the name. NcC ||_dSr)name)r rbrrrr? zmagic_arguments.__init__cCs8t|dds d|_g|_|jdur|j|_t||_|SrZ)rGr[rIrbrUrSrOr\rrrr^s   zmagic_arguments.__call__r)r.r/r0r1r?r^rrrrr`s  r`c@s$eZdZdZdZddZddZdS)ArgMethodWrapperz Base class to define a wrapper for ArgumentParser method. Child class must define either `_method_name` or `add_to_parser`. NcOs||_||_dSr)argsrM)r rerMrrrr?s zArgMethodWrapper.__init__cCs*|dur|}t||j|ji|jdS)6 Add this object's information to the parser. N)rG _method_namererMr_rrrrJszArgMethodWrapper.add_to_parser)r.r/r0r1rgr?rJrrrrrds  rdc@eZdZdZdZdS)argumentzt Store arguments and keywords to pass to add_argument(). Instances also serve to decorate command methods. add_argumentNr.r/r0r1rgrrrrri ric@rh)defaultszt Store arguments and keywords to pass to set_defaults(). Instances also serve to decorate command methods. set_defaultsNrkrrrrrmrlrmc@seZdZdZddZdS)argument_groupzz Store arguments and keywords to pass to add_argument_group(). Instances also serve to decorate command methods. cCs|j|ji|jS)rf)add_argument_grouprerMr_rrrrJ#szargument_group.add_to_parserN)r.r/r0r1rJrrrrros rocs(eZdZdZddZfddZZS)rMz; Provide other keywords to the sub-parser constructor. cKrar)rM)r rMrrrr?,rcz kwds.__init__cstt||}|j|_|Sr)r&rMr^rEr\r,rrr^/sz kwds.__call__)r.r/r0r1r?r^r2rrr,rrM)srM)r`rirorMrD)r1r reIPython.core.errorrIPython.utils.decoratorsrIPython.utils.processrIPython.utils.textrcompilerr rArgumentParserr3rSrDrHobjectrYr`rdrirmrorM__all__rrrrs,T     ("