a Fb&@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)selftextwidthindentr;lib/python3.9/site-packages/IPython/core/magic_arguments.pyr eszMagicHelpFormatter._fill_textcCs|js|||jd\}|Sg}|jdkr:||jnF|j}|||}t|sbd|}|jD]}| d||fqhd |SdS)Nrz<%s>z%s %sz, ) Zoption_stringsZ_metavar_formatterdestnargsextendupperZ _format_argsNAME_REmatchappendjoin)r actionmetavarpartsdefaultZ args_stringZ option_stringrrr_format_action_invocationis     z,MagicHelpFormatter._format_action_invocation:: %cstt|||||dSr)superr add_usage)r usageZactionsgroupsprefix __class__rrr"szMagicHelpFormatter.add_usage)r )__name__ __module__ __qualname____doc__r rr" __classcell__rrr&rr`src sFeZdZdZdddddeddddf fdd Zdd Zd d ZZS) MagicArgumentParserz: An ArgumentParser tweaked for use by IPython magics. N-errorFc s4|dur g}tt|j||||||||| | d dS)N) progr# descriptionepilogparentsformatter_class prefix_charsargument_defaultconflict_handleradd_help)r!r-__init__) r r0r#r1r2r3r4r5r6r7r8r&rrr9s zMagicArgumentParser.__init__cCs t|dS)z5 Raise a catchable error instead of exiting. Nr)r messagerrrr/szMagicArgumentParser.errorcCst|}||S)zL Split a string into an argument list and parse that argument list. )r parse_args)r argstringargvrrrparse_argstringsz#MagicArgumentParser.parse_argstring) r(r)r*r+rr9r/r>r,rrr&rr-sr-cCs|t|di}d|vr$t|dd|d<t|}t|fi|}d}|jdddD]}|||}|durP|}qP||_|S)zB Construct an argument parser using the function decorations. argcmd_kwdsr1r+N)getattr real_namer- decorators add_to_parserZ format_helpr+) magic_funckwdsZarg_nameparsergroupZdecoresultrrrconstruct_parsers   rJcCs |j|S)zA Parse the string of arguments for the given magic function. )rGr>)rEr<rrrr>sr>cCs,|j}|dr |tdd}t|d|S)z& Find the real name of the magic. Zmagic_N argcmd_name)r( startswithlenrA)rEZ magic_namerrrrBs rBc@s eZdZdZddZddZdS) ArgDecoratorzN Base class for decorators to add ArgumentParser information to a method. cCs(t|ddsd|_g|_|j||SN has_argumentsFT)rArPrCrr funcrrr__call__s   zArgDecorator.__call__cCsdS)zD Add this object's information to the parser, if necessary. Nrr rGrHrrrrDszArgDecorator.add_to_parserN)r(r)r*r+rSrDrrrrrNsrNc@s"eZdZdZdddZddZdS)magic_argumentszS Mark the magic as having argparse arguments and possibly adjust the name. NcCs ||_dSr)name)r rVrrrr9szmagic_arguments.__init__cCs8t|ddsd|_g|_|jdur*|j|_t||_|SrO)rArPrCrVrKrJrGrQrrrrSs   zmagic_arguments.__call__)N)r(r)r*r+r9rSrrrrrUs rUc@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)argsrF)r rXrFrrrr9szArgMethodWrapper.__init__cCs*|dur |}t||j|ji|jdS)6 Add this object's information to the parser. N)rA _method_namerXrFrTrrrrDszArgMethodWrapper.add_to_parser)r(r)r*r+rZr9rDrrrrrWsrWc@seZdZdZdZdS)argumentzt Store arguments and keywords to pass to add_argument(). Instances also serve to decorate command methods. add_argumentNr(r)r*r+rZrrrrr[ sr[c@seZdZdZdZdS)defaultszt Store arguments and keywords to pass to set_defaults(). Instances also serve to decorate command methods. Z set_defaultsNr]rrrrr^sr^c@seZdZdZddZdS)argument_groupzz Store arguments and keywords to pass to add_argument_group(). Instances also serve to decorate command methods. cCs|j|ji|jS)rY)Zadd_argument_grouprXrFrTrrrrD#szargument_group.add_to_parserN)r(r)r*r+rDrrrrr_sr_cs(eZdZdZddZfddZZS)rFz; Provide other keywords to the sub-parser constructor. cKs ||_dSr)rF)r rFrrrr9,sz kwds.__init__cstt||}|j|_|Sr)r!rFrSr?rQr&rrrS/sz kwds.__call__)r(r)r*r+r9rSr,rrr&rrF)srF)rUr[r_rFr>)r+r reZIPython.core.errorrZIPython.utils.decoratorsrZIPython.utils.processrZIPython.utils.textrcompilerr rArgumentParserr-rJr>rBobjectrNrUrWr[r^r_rF__all__rrrrs*T     ("