From 9c7626b30265a21fa8f1d0d2684f7468a071361e 2012-05-26 03:20:00
From: Fernando Perez <Fernando.Perez@berkeley.edu>
Date: 2012-05-26 03:20:00
Subject: [PATCH] Settle on cleaner API for magic registration.

The official API will be:

- ip.register_magics(*args): for registering one or more classes or
instances that subclass the main magic.Magics class.  This will be the
*only* method for registering magics that have a signature f(self,
line,...).

- ip.function_as_magic: for registering one-off magics made from a
standalone function with the signatures f(line), f(line, cell) or
f(line, cell=None).

We will support, for backwards compatibility, the old ip.define_magic,
but it will print a deprecation warning.

---

diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py
index d9dc730..352bbda 100644
--- a/IPython/core/interactiveshell.py
+++ b/IPython/core/interactiveshell.py
@@ -1999,9 +1999,10 @@ class InteractiveShell(SingletonConfigurable):
                                    user_magics=mf.UserMagics(self))
         self.configurables.append(self.magics_manager)
 
-        # Expose as public API new_magic and registere_magics
-        self.new_magic = self.magics_manager.new_magic
+        # Expose as public API from the magics manager
         self.register_magics = self.magics_manager.register
+        self.function_as_magic = self.magics_manager.function_as_magic
+        self.define_magic = self.magics_manager._define_magic
 
         self.register_magics(mf.BasicMagics, mf.CodeMagics,
              mf.ConfigMagics, mf.NamespaceMagics, mf.ExecutionMagics,
@@ -2055,16 +2056,6 @@ class InteractiveShell(SingletonConfigurable):
                 result = fn(*args)
             return result
 
-    def define_magic(self, magic_name, func):
-        """Expose own function as magic function for ipython
-
-        Note: this API is now deprecated. Instead, you should use
-        `get_ipython().new_magic`.
-        """
-        warn('Deprecated API, use get_ipython().new_magic: %s\n' %
-             magic_name)
-        return self.new_magic(func, magic_name)
-
     def find_line_magic(self, magic_name):
         """Find and return a line magic by name."""
         return self.magics_manager.magics['line'].get(magic_name)
diff --git a/IPython/core/magic.py b/IPython/core/magic.py
index eb4e569..c0ca043 100644
--- a/IPython/core/magic.py
+++ b/IPython/core/magic.py
@@ -30,7 +30,7 @@ from IPython.external.decorator import decorator
 from IPython.utils.ipstruct import Struct
 from IPython.utils.process import arg_split
 from IPython.utils.traitlets import Bool, Dict, Instance
-from IPython.utils.warn import error
+from IPython.utils.warn import error, warn
 
 #-----------------------------------------------------------------------------
 # Globals
@@ -190,16 +190,31 @@ class MagicsManager(Configurable):
             for mtype in magic_types:
                 self.magics[mtype].update(m.magics[mtype])
 
-    def new_magic(self, func, magic_name=None, magic_type='line'):
+    def function_as_magic(self, func, magic_type='line', magic_name=None):
         """Expose a standalone function as magic function for ipython.
-
         """
 
         # Create the new method in the user_magics and register it in the
         # global table
+        validate_type(magic_type)
+        magic_name = func.func_name if magic_name is None else magic_name
+        setattr(self.user_magics, magic_name, func)
         newm, name = self.user_magics.new_magic(func, magic_type, magic_name)
         _record_magic(self.magics, magic_type, name, newm)
 
+
+    def _define_magic(self, name, func):
+        """Support for deprecated API.
+
+        This method exists only to support the old-style definition of magics.
+        It will eventually be removed.  Deliberately not documented further.
+        """
+        warn('Deprecated API, use function_as_magic or register_magics: %s\n' %
+             name)
+        meth = types.MethodType(func, self.user_magics)
+        setattr(self.user_magics, name, meth)
+        _record_magic(self.magics, 'line', name, meth)
+
 # Key base class that provides the central functionality for magics.
 
 class Magics(object):
@@ -357,13 +372,3 @@ class Magics(object):
         if fn not in self.lsmagic():
             error("%s is not a magic function" % fn)
         self.options_table[fn] = optstr
-
-    def new_magic(self, func, magic_type='line', magic_name=None):
-        """TODO
-        """
-        magic_name = func.func_name if magic_name is None else magic_name
-        validate_type(magic_type)
-        meth = types.MethodType(func, self)
-        setattr(self, magic_name, meth)
-        _record_magic(self.magics, magic_type, magic_name, meth)
-        return meth, magic_name