New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Magic arguments #199
Merged
Merged
Magic arguments #199
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,220 @@ | ||
''' 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. | ||
|
||
''' | ||
#----------------------------------------------------------------------------- | ||
# Copyright (c) 2010, IPython Development Team. | ||
# | ||
# Distributed under the terms of the Modified BSD License. | ||
# | ||
# The full license is in the file COPYING.txt, distributed with this software. | ||
#----------------------------------------------------------------------------- | ||
|
||
# Our own imports | ||
from IPython.external import argparse | ||
from IPython.core.error import UsageError | ||
from IPython.utils.process import arg_split | ||
|
||
|
||
class MagicArgumentParser(argparse.ArgumentParser): | ||
""" An ArgumentParser tweaked for use by IPython magics. | ||
""" | ||
def __init__(self, | ||
prog=None, | ||
usage=None, | ||
description=None, | ||
epilog=None, | ||
version=None, | ||
parents=None, | ||
formatter_class=argparse.HelpFormatter, | ||
prefix_chars='-', | ||
argument_default=None, | ||
conflict_handler='error', | ||
add_help=False): | ||
if parents is None: | ||
parents = [] | ||
super(MagicArgumentParser, self).__init__(prog=prog, usage=usage, | ||
description=description, epilog=epilog, version=version, | ||
parents=parents, formatter_class=formatter_class, | ||
prefix_chars=prefix_chars, argument_default=argument_default, | ||
conflict_handler=conflict_handler, add_help=add_help) | ||
|
||
def error(self, message): | ||
""" Raise a catchable error instead of exiting. | ||
""" | ||
raise UsageError(message) | ||
|
||
def parse_argstring(self, argstring): | ||
""" Split a string into an argument list and parse that argument list. | ||
""" | ||
argv = arg_split(argstring) | ||
return self.parse_args(argv) | ||
|
||
|
||
def construct_parser(magic_func): | ||
""" Construct an argument parser using the function decorations. | ||
""" | ||
kwds = getattr(magic_func, 'argcmd_kwds', {}) | ||
if 'description' not in kwds: | ||
kwds['description'] = getattr(magic_func, '__doc__', None) | ||
arg_name = real_name(magic_func) | ||
parser = MagicArgumentParser(arg_name, **kwds) | ||
# Reverse the list of decorators in order to apply them in the | ||
# order in which they appear in the source. | ||
group = None | ||
for deco in magic_func.decorators[::-1]: | ||
result = deco.add_to_parser(parser, group) | ||
if result is not None: | ||
group = result | ||
|
||
# Replace the starting 'usage: ' with IPython's %. | ||
help_text = parser.format_help() | ||
if help_text.startswith('usage: '): | ||
help_text = help_text.replace('usage: ', '%', 1) | ||
else: | ||
help_text = '%' + help_text | ||
|
||
# Replace the magic function's docstring with the full help text. | ||
magic_func.__doc__ = help_text | ||
|
||
return parser | ||
|
||
|
||
def parse_argstring(magic_func, argstring): | ||
""" Parse the string of arguments for the given magic function. | ||
""" | ||
args = magic_func.parser.parse_argstring(argstring) | ||
return args | ||
|
||
|
||
def real_name(magic_func): | ||
""" Find the real name of the magic. | ||
""" | ||
magic_name = magic_func.__name__ | ||
if magic_name.startswith('magic_'): | ||
magic_name = magic_name[len('magic_'):] | ||
arg_name = getattr(magic_func, 'argcmd_name', magic_name) | ||
return arg_name | ||
|
||
|
||
class ArgDecorator(object): | ||
""" Base class for decorators to add ArgumentParser information to a method. | ||
""" | ||
|
||
def __call__(self, func): | ||
if not getattr(func, 'has_arguments', False): | ||
func.has_arguments = True | ||
func.decorators = [] | ||
func.decorators.append(self) | ||
return func | ||
|
||
def add_to_parser(self, parser, group): | ||
""" Add this object's information to the parser, if necessary. | ||
""" | ||
pass | ||
|
||
|
||
class magic_arguments(ArgDecorator): | ||
""" Mark the magic as having argparse arguments and possibly adjust the | ||
name. | ||
""" | ||
|
||
def __init__(self, name=None): | ||
self.name = name | ||
|
||
def __call__(self, func): | ||
if not getattr(func, 'has_arguments', False): | ||
func.has_arguments = True | ||
func.decorators = [] | ||
if self.name is not None: | ||
func.argcmd_name = self.name | ||
# This should be the first decorator in the list of decorators, thus the | ||
# last to execute. Build the parser. | ||
func.parser = construct_parser(func) | ||
return func | ||
|
||
|
||
class argument(ArgDecorator): | ||
""" Store arguments and keywords to pass to add_argument(). | ||
|
||
Instances also serve to decorate command methods. | ||
""" | ||
def __init__(self, *args, **kwds): | ||
self.args = args | ||
self.kwds = kwds | ||
|
||
def add_to_parser(self, parser, group): | ||
""" Add this object's information to the parser. | ||
""" | ||
if group is not None: | ||
parser = group | ||
parser.add_argument(*self.args, **self.kwds) | ||
return None | ||
|
||
|
||
class argument_group(ArgDecorator): | ||
""" Store arguments and keywords to pass to add_argument_group(). | ||
|
||
Instances also serve to decorate command methods. | ||
""" | ||
def __init__(self, *args, **kwds): | ||
self.args = args | ||
self.kwds = kwds | ||
|
||
def add_to_parser(self, parser, group): | ||
""" Add this object's information to the parser. | ||
""" | ||
group = parser.add_argument_group(*self.args, **self.kwds) | ||
return group | ||
|
||
|
||
class kwds(ArgDecorator): | ||
""" Provide other keywords to the sub-parser constructor. | ||
""" | ||
def __init__(self, **kwds): | ||
self.kwds = kwds | ||
|
||
def __call__(self, func): | ||
func = super(kwds, self).__call__(func) | ||
func.argcmd_kwds = self.kwds | ||
return func | ||
|
||
|
||
__all__ = ['magic_arguments', 'argument', 'argument_group', 'kwds', | ||
'parse_argstring'] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
#----------------------------------------------------------------------------- | ||
# Copyright (c) 2010, IPython Development Team. | ||
# | ||
# Distributed under the terms of the Modified BSD License. | ||
# | ||
# The full license is in the file COPYING.txt, distributed with this software. | ||
#----------------------------------------------------------------------------- | ||
|
||
from nose.tools import assert_equal, assert_true | ||
|
||
from IPython.external import argparse | ||
from IPython.core.magic_arguments import (argument, argument_group, kwds, | ||
magic_arguments, parse_argstring, real_name) | ||
|
||
|
||
@magic_arguments() | ||
@argument('-f', '--foo', help="an argument") | ||
def magic_foo1(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(magic_foo1, args) | ||
|
||
@magic_arguments() | ||
def magic_foo2(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(magic_foo2, args) | ||
|
||
@magic_arguments() | ||
@argument('-f', '--foo', help="an argument") | ||
@argument_group('Group') | ||
@argument('-b', '--bar', help="a grouped argument") | ||
@argument_group('Second Group') | ||
@argument('-z', '--baz', help="another grouped argument") | ||
def magic_foo3(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(magic_foo3, args) | ||
|
||
@magic_arguments() | ||
@kwds(argument_default=argparse.SUPPRESS) | ||
@argument('-f', '--foo', help="an argument") | ||
def magic_foo4(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(magic_foo4, args) | ||
|
||
@magic_arguments('frobnicate') | ||
@argument('-f', '--foo', help="an argument") | ||
def magic_foo5(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(magic_foo5, args) | ||
|
||
@magic_arguments() | ||
@argument('-f', '--foo', help="an argument") | ||
def magic_magic_foo(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(magic_magic_foo, args) | ||
|
||
@magic_arguments() | ||
@argument('-f', '--foo', help="an argument") | ||
def foo(self, args): | ||
""" A docstring. | ||
""" | ||
return parse_argstring(foo, args) | ||
|
||
def test_magic_arguments(): | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. we'll convert these to use @Parametric. For all its flaws, it's still better than the impossible to debug situation produced by nose's yield tests, which return an alternate stack (the one from nose) when they fail. In the future, please use @Parametric for these situations. |
||
# Ideally, these would be doctests, but I could not get it to work. | ||
yield assert_equal, magic_foo1.__doc__, '%foo1 [-f FOO]\n\nA docstring.\n\noptional arguments:\n -f FOO, --foo FOO an argument\n' | ||
yield assert_equal, getattr(magic_foo1, 'argcmd_name', None), None | ||
yield assert_equal, real_name(magic_foo1), 'foo1' | ||
yield assert_equal, magic_foo1(None, ''), argparse.Namespace(foo=None) | ||
yield assert_true, hasattr(magic_foo1, 'has_arguments') | ||
|
||
yield assert_equal, magic_foo2.__doc__, '%foo2\n\nA docstring.\n' | ||
yield assert_equal, getattr(magic_foo2, 'argcmd_name', None), None | ||
yield assert_equal, real_name(magic_foo2), 'foo2' | ||
yield assert_equal, magic_foo2(None, ''), argparse.Namespace() | ||
yield assert_true, hasattr(magic_foo2, 'has_arguments') | ||
|
||
yield assert_equal, magic_foo3.__doc__, '%foo3 [-f FOO] [-b BAR] [-z BAZ]\n\nA docstring.\n\noptional arguments:\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' | ||
yield assert_equal, getattr(magic_foo3, 'argcmd_name', None), None | ||
yield assert_equal, real_name(magic_foo3), 'foo3' | ||
yield assert_equal, magic_foo3(None, ''), argparse.Namespace(bar=None, baz=None, foo=None) | ||
yield assert_true, hasattr(magic_foo3, 'has_arguments') | ||
|
||
yield assert_equal, magic_foo4.__doc__, '%foo4 [-f FOO]\n\nA docstring.\n\noptional arguments:\n -f FOO, --foo FOO an argument\n' | ||
yield assert_equal, getattr(magic_foo4, 'argcmd_name', None), None | ||
yield assert_equal, real_name(magic_foo4), 'foo4' | ||
yield assert_equal, magic_foo4(None, ''), argparse.Namespace() | ||
yield assert_true, hasattr(magic_foo4, 'has_arguments') | ||
|
||
yield assert_equal, magic_foo5.__doc__, '%frobnicate [-f FOO]\n\nA docstring.\n\noptional arguments:\n -f FOO, --foo FOO an argument\n' | ||
yield assert_equal, getattr(magic_foo5, 'argcmd_name', None), 'frobnicate' | ||
yield assert_equal, real_name(magic_foo5), 'frobnicate' | ||
yield assert_equal, magic_foo5(None, ''), argparse.Namespace(foo=None) | ||
yield assert_true, hasattr(magic_foo5, 'has_arguments') | ||
|
||
yield assert_equal, magic_magic_foo.__doc__, '%magic_foo [-f FOO]\n\nA docstring.\n\noptional arguments:\n -f FOO, --foo FOO an argument\n' | ||
yield assert_equal, getattr(magic_magic_foo, 'argcmd_name', None), None | ||
yield assert_equal, real_name(magic_magic_foo), 'magic_foo' | ||
yield assert_equal, magic_magic_foo(None, ''), argparse.Namespace(foo=None) | ||
yield assert_true, hasattr(magic_magic_foo, 'has_arguments') | ||
|
||
yield assert_equal, foo.__doc__, '%foo [-f FOO]\n\nA docstring.\n\noptional arguments:\n -f FOO, --foo FOO an argument\n' | ||
yield assert_equal, getattr(foo, 'argcmd_name', None), None | ||
yield assert_equal, real_name(foo), 'foo' | ||
yield assert_equal, foo(None, ''), argparse.Namespace(foo=None) | ||
yield assert_true, hasattr(foo, 'has_arguments') | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can just return the value straight away, no need to create that intermediate variable.
Don't worry though: the pull request is in almost perfect shape, so I'll do the cleanup as part of the merge.