1  #-----------------------------------------------------------------------------
   2  # Copyright (C) 2010-2011, IPython Development Team.
   3  #
   4  # Distributed under the terms of the Modified BSD License.
   5  #
   6  # The full license is in the file COPYING.txt, distributed with this software.
   7  #-----------------------------------------------------------------------------
   8  
   9  import argparse
  10  import sys
  11  
  12  from IPython.core.magic_arguments import (argument, argument_group, kwds,
  13      magic_arguments, parse_argstring, real_name)
  14  
  15  LEADING_SPACE = "" if sys.version_info > (3, 13) else " "
  16  
  17  
  18  @magic_arguments()
  19  @argument('-f', '--foo', help="an argument")
  20  def magic_foo1(self, args):
  21      """ A docstring.
  22      """
  23      return parse_argstring(magic_foo1, args)
  24  
  25  
  26  @magic_arguments()
  27  def magic_foo2(self, args):
  28      """ A docstring.
  29      """
  30      return parse_argstring(magic_foo2, args)
  31  
  32  
  33  @magic_arguments()
  34  @argument('-f', '--foo', help="an argument")
  35  @argument_group('Group')
  36  @argument('-b', '--bar', help="a grouped argument")
  37  @argument_group('Second Group')
  38  @argument('-z', '--baz', help="another grouped argument")
  39  def magic_foo3(self, args):
  40      """ A docstring.
  41      """
  42      return parse_argstring(magic_foo3, args)
  43  
  44  
  45  @magic_arguments()
  46  @kwds(argument_default=argparse.SUPPRESS)
  47  @argument('-f', '--foo', help="an argument")
  48  def magic_foo4(self, args):
  49      """ A docstring.
  50      """
  51      return parse_argstring(magic_foo4, args)
  52  
  53  
  54  @magic_arguments('frobnicate')
  55  @argument('-f', '--foo', help="an argument")
  56  def magic_foo5(self, args):
  57      """ A docstring.
  58      """
  59      return parse_argstring(magic_foo5, args)
  60  
  61  
  62  @magic_arguments()
  63  @argument('-f', '--foo', help="an argument")
  64  def magic_magic_foo(self, args):
  65      """ A docstring.
  66      """
  67      return parse_argstring(magic_magic_foo, args)
  68  
  69  
  70  @magic_arguments()
  71  @argument('-f', '--foo', help="an argument")
  72  def foo(self, args):
  73      """ A docstring.
  74      """
  75      return parse_argstring(foo, args)
  76  
  77  
  78  def test_magic_arguments():
  79      # “optional arguments” was replaced with “options” in argparse help
  80      # https://docs.python.org/3/whatsnew/3.10.html#argparse
  81      # https://bugs.python.org/issue9694
  82      options = "optional arguments" if sys.version_info < (3, 10) else "options"
  83  
  84      assert (
  85          magic_foo1.__doc__
  86          == f"::\n\n  %foo1 [-f FOO]\n\n{LEADING_SPACE}A docstring.\n\n{options}:\n  -f FOO, --foo FOO  an argument\n"
  87      )
  88      assert getattr(magic_foo1, "argcmd_name", None) == None
  89      assert real_name(magic_foo1) == "foo1"
  90      assert magic_foo1(None, "") == argparse.Namespace(foo=None)
  91      assert hasattr(magic_foo1, "has_arguments")
  92  
  93      assert magic_foo2.__doc__ == f"::\n\n  %foo2\n\n{LEADING_SPACE}A docstring.\n"
  94      assert getattr(magic_foo2, "argcmd_name", None) == None
  95      assert real_name(magic_foo2) == "foo2"
  96      assert magic_foo2(None, "") == argparse.Namespace()
  97      assert hasattr(magic_foo2, "has_arguments")
  98  
  99      assert (
 100          magic_foo3.__doc__
 101          == f"::\n\n  %foo3 [-f FOO] [-b BAR] [-z BAZ]\n\n{LEADING_SPACE}A docstring.\n\n{options}:\n  -f FOO, --foo FOO  an argument\n\nGroup:\n  -b BAR, --bar BAR  a grouped argument\n\nSecond Group:\n  -z BAZ, --baz BAZ  another grouped argument\n"
 102      )
 103      assert getattr(magic_foo3, "argcmd_name", None) == None
 104      assert real_name(magic_foo3) == "foo3"
 105      assert magic_foo3(None, "") == argparse.Namespace(bar=None, baz=None, foo=None)
 106      assert hasattr(magic_foo3, "has_arguments")
 107  
 108      assert (
 109          magic_foo4.__doc__
 110          == f"::\n\n  %foo4 [-f FOO]\n\n{LEADING_SPACE}A docstring.\n\n{options}:\n  -f FOO, --foo FOO  an argument\n"
 111      )
 112      assert getattr(magic_foo4, "argcmd_name", None) == None
 113      assert real_name(magic_foo4) == "foo4"
 114      assert magic_foo4(None, "") == argparse.Namespace()
 115      assert hasattr(magic_foo4, "has_arguments")
 116  
 117      assert (
 118          magic_foo5.__doc__
 119          == f"::\n\n  %frobnicate [-f FOO]\n\n{LEADING_SPACE}A docstring.\n\n{options}:\n  -f FOO, --foo FOO  an argument\n"
 120      )
 121      assert getattr(magic_foo5, "argcmd_name", None) == "frobnicate"
 122      assert real_name(magic_foo5) == "frobnicate"
 123      assert magic_foo5(None, "") == argparse.Namespace(foo=None)
 124      assert hasattr(magic_foo5, "has_arguments")
 125  
 126      assert (
 127          magic_magic_foo.__doc__
 128          == f"::\n\n  %magic_foo [-f FOO]\n\n{LEADING_SPACE}A docstring.\n\n{options}:\n  -f FOO, --foo FOO  an argument\n"
 129      )
 130      assert getattr(magic_magic_foo, "argcmd_name", None) == None
 131      assert real_name(magic_magic_foo) == "magic_foo"
 132      assert magic_magic_foo(None, "") == argparse.Namespace(foo=None)
 133      assert hasattr(magic_magic_foo, "has_arguments")
 134  
 135      assert (
 136          foo.__doc__
 137          == f"::\n\n  %foo [-f FOO]\n\n{LEADING_SPACE}A docstring.\n\n{options}:\n  -f FOO, --foo FOO  an argument\n"
 138      )
 139      assert getattr(foo, "argcmd_name", None) == None
 140      assert real_name(foo) == "foo"
 141      assert foo(None, "") == argparse.Namespace(foo=None)
 142      assert hasattr(foo, "has_arguments")
 143