^h&~SrSSKrSSKrSSKJr SSKJr SSKJr SSK J r \R"S5r \"SS \R55r"S S \R5rS rS rSr"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r/SQrg)aA 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_-]*$c<^\rSrSrSrSrSrSU4SjjrSrU=r $)MagicHelpFormatter`z@A HelpFormatter with a couple of changes to meet our needs. cV[RRU[U5X#5$N)argparseRawDescriptionHelpFormatter _fill_textr)selftextwidthindents V/home/james-whalen/.local/lib/python3.13/site-packages/IPython/core/magic_arguments.pyrMagicHelpFormatter._fill_textes"33>>tVD\SXaacUR(d%URXR5"S5unU$/nURS:XaUR UR5 OuURR 5nUR X5n[RU5(dSU-nURHnURU<SU<35 M SRU5$)Nrz<%s> z, ) option_strings_metavar_formatterdestnargsextendupper _format_argsNAME_REmatchappendjoin)ractionmetavarpartsdefault args_string option_strings r_format_action_invocation,MagicHelpFormatter._format_action_invocationis$$..v{{CAFHGNE||q  V223 !++++-"//@ }}[11"(;"6K%+%:%:MLLM;!GH&;99U# #rc.>[[U] XX45 gr )superr add_usage)rusageactionsgroupsprefix __class__s rr/MagicHelpFormatter.add_usages  $1%&Qr)z:: %) __name__ __module__ __qualname____firstlineno____doc__rr+r/__static_attributes__ __classcell__r4s@rr r `sb$:RRrr c P^\rSrSrSrSSSSS\SSSS4 U4SjjrSrS rS r U=r $) MagicArgumentParserz9An ArgumentParser tweaked for use by IPython magics. N-errorFc :>Uc/n[[U] XX4XVXxXS9 g)N) progr0 descriptionepilogparentsformatter_class prefix_charsargument_defaultconflict_handleradd_help)r.r@__init__) rrEr0rFrGrHrIrJrKrLrMr4s rrNMagicArgumentParser.__init__s3 ?G !41t#%- 2 Brc[U5e)z4Raise a catchable error instead of exiting. r)rmessages rrCMagicArgumentParser.errors!!rc:[U5nURU5$)zKSplit a string into an argument list and parse that argument list. )r parse_args)r argstringargvs rparse_argstring#MagicArgumentParser.parse_argstrings#t$$rr6) r7r8r9r:r;r rNrCrWr<r=r>s@rr@r@s=!!3!"&")B&" %%rr@c [US05nSU;a[USS5US'[U5n[U40UD6nSnURSSS2HnUR X45nUcMUnM UR 5UlU$)zAConstruct an argument parser using the function decorations. argcmd_kwdsrFr;N)getattr real_namer@ decorators add_to_parser format_helpr;) magic_funckwdsarg_nameparsergroupdecoresults rconstruct_parserrhs :}b 1DD %j)TB]$H  2T 2F E%%dd+##F2  E,  ++-J Mrc8URRU5$)z@Parse the string of arguments for the given magic function. )rdrW)rarUs rrWrWs    , ,Y 77rc|URnURS5(aU[S5Sn[USU5$)z%Find the real name of the magic. magic_N argcmd_name)r7 startswithlenr\)ra magic_names rr]r]s?$$JX&&H / :}j 99rc$\rSrSrSrSrSrSrg) ArgDecoratorzMBase class for decorators to add ArgumentParser information to a method. c|[USS5(dSUl/UlURRU5 U$N has_argumentsFT)r\rur^r#rfuncs r__call__ArgDecorator.__call__s7t_e44!%D  DO t$ rcg)zCAdd this object's information to the parser, if necessary. Nr6rrdres rr_ArgDecorator.add_to_parsers rr6N)r7r8r9r:r;rxr_r<r6rrrqrqs rrqc(\rSrSrSrSSjrSrSrg)magic_argumentszJMark the magic as having argparse arguments and possibly adjust the name. NcXlgr name)rrs rrNmagic_arguments.__init__ rc[USS5(dSUl/UlURbURUl[ U5UlU$rt)r\rur^rrlrhrdrvs rrxmagic_arguments.__call__sIt_e44!%D  DO 99 #yyD 't,  rrr )r7r8r9r:r;rNrxr<r6rrr~r~s rr~c0\rSrSr%Sr\\S'SrSrSr g)ArgMethodWrapperz Base class to define a wrapper for ArgumentParser method. Child class must define either `_method_name` or `add_to_parser`. _method_namecXlX lgr argsrb)rrrbs rrNArgMethodWrapper.__init__s   rclUbUn[XR5"UR0URD6 g)5Add this object's information to the parser. N)r\rrrbr{s rr_ArgMethodWrapper.add_to_parsers2  F))*DIICCrrN) r7r8r9r:r;str__annotations__rNr_r<r6rrrrsrrc\rSrSrSrSrSrg)argumenti zkStore arguments and keywords to pass to add_argument(). Instances also serve to decorate command methods. add_argumentr6Nr7r8r9r:r;rr<r6rrrr "Lrrc\rSrSrSrSrSrg)defaultsizkStore arguments and keywords to pass to set_defaults(). Instances also serve to decorate command methods. set_defaultsr6Nrr6rrrrrrrc\rSrSrSrSrSrg)argument_groupizqStore arguments and keywords to pass to add_argument_group(). Instances also serve to decorate command methods. cNUR"UR0URD6$)r)add_argument_grouprrbr{s rr_argument_group.add_to_parser#s"(($))AtyyAArr6N)r7r8r9r:r;r_r<r6rrrrs  Brrc2^\rSrSrSrSrU4SjrSrU=r$)rbi)z:Provide other keywords to the sub-parser constructor. c Xlgr rb)rrbs rrN kwds.__init__,rrcP>[[U] U5nURUlU$r )r.rbrxrZ)rrwr4s rrx kwds.__call__/s%T4)$/99 rr) r7r8r9r:r;rNrxr<r=r>s@rrbrb)srrb)r~rrrbrW)r;r reIPython.core.errorrIPython.utils.decoratorsrIPython.utils.processrIPython.utils.textrcompiler!rr ArgumentParserr@rhrWr]objectrqr~rrrrrb__all__r6rrrsLh **+% **/ 0&R==&R&RP%(11%D,8 : 6 "l(|0"""" B% B <  r