From 180f7916380ffaa11a85a39c31e2fc26a99daba8 2011-11-25 00:27:28 From: Thomas Kluyver Date: 2011-11-25 00:27:28 Subject: [PATCH] Improve documentation for extensions, and for storemagic extension. --- diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py index 1c232c9..89aa582 100644 --- a/IPython/core/interactiveshell.py +++ b/IPython/core/interactiveshell.py @@ -2000,14 +2000,16 @@ class InteractiveShell(SingletonConfigurable, Magic): def define_magic(self, magicname, func): """Expose own function as magic function for ipython + + Example:: - def foo_impl(self,parameter_s=''): - 'My very own magic!. (Use docstrings, IPython reads them).' - print 'Magic function. Passed parameter is between < >:' - print '<%s>' % parameter_s - print 'The self object is:',self + def foo_impl(self,parameter_s=''): + 'My very own magic!. (Use docstrings, IPython reads them).' + print 'Magic function. Passed parameter is between < >:' + print '<%s>' % parameter_s + print 'The self object is:', self - self.define_magic('foo',foo_impl) + ip.define_magic('foo',foo_impl) """ im = types.MethodType(func,self) old = getattr(self, "magic_" + magicname, None) diff --git a/IPython/extensions/storemagic.py b/IPython/extensions/storemagic.py index ce253c4..92f94c9 100644 --- a/IPython/extensions/storemagic.py +++ b/IPython/extensions/storemagic.py @@ -2,16 +2,18 @@ """ %store magic for lightweight persistence. -Stores variables, aliases etc. in PickleShare database. +Stores variables, aliases and macros in IPython's database. Stored values will +be automatically restored whenever the extension is loaded. -To enable this functionality, run:: +To enable this functionality, list it in your default profile +`ipython_config.py` file:: - %load_ext storemagic + c.InteractiveShellApp.extensions = ['storemagic'] -in your IPython session. If you always want it enabled, you can list it in -your default profile `ipython_config.py` file:: +Or to use it temporarily, run this in your IPython session:: + + %load_ext storemagic - c.InteractiveShellApp.extensions = ['storemagic'] """ from IPython.core.error import TryNext, UsageError @@ -54,34 +56,33 @@ def restore_data(ip): def magic_store(self, parameter_s=''): """Lightweight persistence for python variables. - Example: - - ville@badger[~]|1> A = ['hello',10,'world']\\ - ville@badger[~]|2> %store A\\ - ville@badger[~]|3> Exit + Example:: - (IPython session is closed and started again...) + In [1]: l = ['hello',10,'world'] + In [2]: %store l + In [3]: exit - ville@badger:~$ ipython -p pysh\\ - ville@badger[~]|1> print A + (IPython session is closed and started again...) - ['hello', 10, 'world'] + ville@badger:~$ ipython + In [1]: l + Out[1]: ['hello', 10, 'world'] Usage: - %store - Show list of all variables and their current values\\ - %store - Store the *current* value of the variable to disk\\ - %store -d - Remove the variable and its value from storage\\ - %store -z - Remove all variables from storage\\ - %store -r - Refresh all variables from store (delete current vals)\\ - %store foo >a.txt - Store value of foo to new file a.txt\\ - %store foo >>a.txt - Append value of foo to file a.txt\\ + * ``%store`` - Show list of all variables and their current values + * ``%store spam`` - Store the *current* value of the variable spam to disk + * ``%store -d spam`` - Remove the variable and its value from storage + * ``%store -z`` - Remove all variables from storage + * ``%store -r`` - Refresh all variables from store (delete current vals) + * ``%store foo >a.txt`` - Store value of foo to new file a.txt + * ``%store foo >>a.txt`` - Append value of foo to file a.txt It should be noted that if you change the value of a variable, you need to %store it again if you want to persist the new value. Note also that the variables will need to be pickleable; most basic - python types can be safely %stored. + python types can be safely %store'd. Also aliases can be %store'd across sessions. """ diff --git a/docs/source/config/extensions/index.txt b/docs/source/config/extensions/index.txt index 561397d..300a751 100644 --- a/docs/source/config/extensions/index.txt +++ b/docs/source/config/extensions/index.txt @@ -29,6 +29,10 @@ The :func:`load_ipython_extension` will be called again is you load or reload the extension again. It is up to the extension author to add code to manage that. +Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`, +:meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and +:meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading). + You can put your extension modules anywhere you want, as long as they can be imported by Python's standard import mechanism. However, to make it easy to write extensions, you can also put your extensions in @@ -68,4 +72,5 @@ Extensions bundled with IPython autoreload parallelmagic + storemagic sympyprinting diff --git a/docs/source/config/extensions/storemagic.txt b/docs/source/config/extensions/storemagic.txt new file mode 100644 index 0000000..b860c7e --- /dev/null +++ b/docs/source/config/extensions/storemagic.txt @@ -0,0 +1,8 @@ +.. _extensions_storemagic: + +========== +storemagic +========== + +.. automodule:: IPython.extensions.storemagic + :members: magic_store diff --git a/docs/source/whatsnew/development.txt b/docs/source/whatsnew/development.txt index 1319f40..c209071 100644 --- a/docs/source/whatsnew/development.txt +++ b/docs/source/whatsnew/development.txt @@ -62,7 +62,7 @@ New features Terminal frontend by default (:ghpull:`838`). * **%store**: The ``%store`` magic from earlier versions has been updated and - placed in an extension, 'storemagic'. Add 'storemagic' to ``c.InteractiveShellApp.extensions`` + placed in an extension, :ref:`extensions_storemagic`. Add 'storemagic' to ``c.InteractiveShellApp.extensions`` in ipython_config.py to enable it (:ghpull:`1029`).