##// END OF EJS Templates
update %store magic docstring...
MinRK -
Show More
@@ -1,224 +1,227
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 %store magic for lightweight persistence.
3 %store magic for lightweight persistence.
4
4
5 Stores variables, aliases and macros in IPython's database.
5 Stores variables, aliases and macros in IPython's database.
6
6
7 To automatically restore stored variables at startup, add this to your
7 To automatically restore stored variables at startup, add this to your
8 :file:`ipython_config.py` file::
8 :file:`ipython_config.py` file::
9
9
10 c.StoreMagic.autorestore = True
10 c.StoreMagic.autorestore = True
11 """
11 """
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Copyright (c) 2012, The IPython Development Team.
13 # Copyright (c) 2012, The IPython Development Team.
14 #
14 #
15 # Distributed under the terms of the Modified BSD License.
15 # Distributed under the terms of the Modified BSD License.
16 #
16 #
17 # The full license is in the file COPYING.txt, distributed with this software.
17 # The full license is in the file COPYING.txt, distributed with this software.
18 #-----------------------------------------------------------------------------
18 #-----------------------------------------------------------------------------
19
19
20 #-----------------------------------------------------------------------------
20 #-----------------------------------------------------------------------------
21 # Imports
21 # Imports
22 #-----------------------------------------------------------------------------
22 #-----------------------------------------------------------------------------
23
23
24 # Stdlib
24 # Stdlib
25 import inspect, os, sys, textwrap
25 import inspect, os, sys, textwrap
26
26
27 # Our own
27 # Our own
28 from IPython.core.error import UsageError
28 from IPython.core.error import UsageError
29 from IPython.core.fakemodule import FakeModule
29 from IPython.core.fakemodule import FakeModule
30 from IPython.core.magic import Magics, magics_class, line_magic
30 from IPython.core.magic import Magics, magics_class, line_magic
31 from IPython.testing.skipdoctest import skip_doctest
31 from IPython.testing.skipdoctest import skip_doctest
32
32
33 #-----------------------------------------------------------------------------
33 #-----------------------------------------------------------------------------
34 # Functions and classes
34 # Functions and classes
35 #-----------------------------------------------------------------------------
35 #-----------------------------------------------------------------------------
36
36
37 def restore_aliases(ip):
37 def restore_aliases(ip):
38 staliases = ip.db.get('stored_aliases', {})
38 staliases = ip.db.get('stored_aliases', {})
39 for k,v in staliases.items():
39 for k,v in staliases.items():
40 #print "restore alias",k,v # dbg
40 #print "restore alias",k,v # dbg
41 #self.alias_table[k] = v
41 #self.alias_table[k] = v
42 ip.alias_manager.define_alias(k,v)
42 ip.alias_manager.define_alias(k,v)
43
43
44
44
45 def refresh_variables(ip):
45 def refresh_variables(ip):
46 db = ip.db
46 db = ip.db
47 for key in db.keys('autorestore/*'):
47 for key in db.keys('autorestore/*'):
48 # strip autorestore
48 # strip autorestore
49 justkey = os.path.basename(key)
49 justkey = os.path.basename(key)
50 try:
50 try:
51 obj = db[key]
51 obj = db[key]
52 except KeyError:
52 except KeyError:
53 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % justkey
53 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % justkey
54 print "The error was:", sys.exc_info()[0]
54 print "The error was:", sys.exc_info()[0]
55 else:
55 else:
56 #print "restored",justkey,"=",obj #dbg
56 #print "restored",justkey,"=",obj #dbg
57 ip.user_ns[justkey] = obj
57 ip.user_ns[justkey] = obj
58
58
59
59
60 def restore_dhist(ip):
60 def restore_dhist(ip):
61 ip.user_ns['_dh'] = ip.db.get('dhist',[])
61 ip.user_ns['_dh'] = ip.db.get('dhist',[])
62
62
63
63
64 def restore_data(ip):
64 def restore_data(ip):
65 refresh_variables(ip)
65 refresh_variables(ip)
66 restore_aliases(ip)
66 restore_aliases(ip)
67 restore_dhist(ip)
67 restore_dhist(ip)
68
68
69
69
70 @magics_class
70 @magics_class
71 class StoreMagics(Magics):
71 class StoreMagics(Magics):
72 """Lightweight persistence for python variables.
72 """Lightweight persistence for python variables.
73
73
74 Provides the %store magic."""
74 Provides the %store magic."""
75
75
76 @skip_doctest
76 @skip_doctest
77 @line_magic
77 @line_magic
78 def store(self, parameter_s=''):
78 def store(self, parameter_s=''):
79 """Lightweight persistence for python variables.
79 """Lightweight persistence for python variables.
80
80
81 Example::
81 Example::
82
82
83 In [1]: l = ['hello',10,'world']
83 In [1]: l = ['hello',10,'world']
84 In [2]: %store l
84 In [2]: %store l
85 In [3]: exit
85 In [3]: exit
86
86
87 (IPython session is closed and started again...)
87 (IPython session is closed and started again...)
88
88
89 ville@badger:~$ ipython
89 ville@badger:~$ ipython
90 In [1]: l
90 In [1]: l
91 Out[1]: ['hello', 10, 'world']
91 NameError: name 'l' is not defined
92 In [2]: %store -r
93 In [3]: l
94 Out[3]: ['hello', 10, 'world']
92
95
93 Usage:
96 Usage:
94
97
95 * ``%store`` - Show list of all variables and their current
98 * ``%store`` - Show list of all variables and their current
96 values
99 values
97 * ``%store spam`` - Store the *current* value of the variable spam
100 * ``%store spam`` - Store the *current* value of the variable spam
98 to disk
101 to disk
99 * ``%store -d spam`` - Remove the variable and its value from storage
102 * ``%store -d spam`` - Remove the variable and its value from storage
100 * ``%store -z`` - Remove all variables from storage
103 * ``%store -z`` - Remove all variables from storage
101 * ``%store -r`` - Refresh all variables from store (delete
104 * ``%store -r`` - Refresh all variables from store (overwrite
102 current vals)
105 current vals)
103 * ``%store -r spam bar`` - Refresh specified variables from store
106 * ``%store -r spam bar`` - Refresh specified variables from store
104 (delete current val)
107 (delete current val)
105 * ``%store foo >a.txt`` - Store value of foo to new file a.txt
108 * ``%store foo >a.txt`` - Store value of foo to new file a.txt
106 * ``%store foo >>a.txt`` - Append value of foo to file a.txt
109 * ``%store foo >>a.txt`` - Append value of foo to file a.txt
107
110
108 It should be noted that if you change the value of a variable, you
111 It should be noted that if you change the value of a variable, you
109 need to %store it again if you want to persist the new value.
112 need to %store it again if you want to persist the new value.
110
113
111 Note also that the variables will need to be pickleable; most basic
114 Note also that the variables will need to be pickleable; most basic
112 python types can be safely %store'd.
115 python types can be safely %store'd.
113
116
114 Also aliases can be %store'd across sessions.
117 Also aliases can be %store'd across sessions.
115 """
118 """
116
119
117 opts,argsl = self.parse_options(parameter_s,'drz',mode='string')
120 opts,argsl = self.parse_options(parameter_s,'drz',mode='string')
118 args = argsl.split(None,1)
121 args = argsl.split(None,1)
119 ip = self.shell
122 ip = self.shell
120 db = ip.db
123 db = ip.db
121 # delete
124 # delete
122 if 'd' in opts:
125 if 'd' in opts:
123 try:
126 try:
124 todel = args[0]
127 todel = args[0]
125 except IndexError:
128 except IndexError:
126 raise UsageError('You must provide the variable to forget')
129 raise UsageError('You must provide the variable to forget')
127 else:
130 else:
128 try:
131 try:
129 del db['autorestore/' + todel]
132 del db['autorestore/' + todel]
130 except:
133 except:
131 raise UsageError("Can't delete variable '%s'" % todel)
134 raise UsageError("Can't delete variable '%s'" % todel)
132 # reset
135 # reset
133 elif 'z' in opts:
136 elif 'z' in opts:
134 for k in db.keys('autorestore/*'):
137 for k in db.keys('autorestore/*'):
135 del db[k]
138 del db[k]
136
139
137 elif 'r' in opts:
140 elif 'r' in opts:
138 if args:
141 if args:
139 for arg in args:
142 for arg in args:
140 try:
143 try:
141 obj = db['autorestore/' + arg]
144 obj = db['autorestore/' + arg]
142 except KeyError:
145 except KeyError:
143 print "no stored variable %s" % arg
146 print "no stored variable %s" % arg
144 else:
147 else:
145 ip.user_ns[arg] = obj
148 ip.user_ns[arg] = obj
146 else:
149 else:
147 refresh_variables(ip)
150 refresh_variables(ip)
148
151
149 # run without arguments -> list variables & values
152 # run without arguments -> list variables & values
150 elif not args:
153 elif not args:
151 vars = db.keys('autorestore/*')
154 vars = db.keys('autorestore/*')
152 vars.sort()
155 vars.sort()
153 if vars:
156 if vars:
154 size = max(map(len, vars))
157 size = max(map(len, vars))
155 else:
158 else:
156 size = 0
159 size = 0
157
160
158 print 'Stored variables and their in-db values:'
161 print 'Stored variables and their in-db values:'
159 fmt = '%-'+str(size)+'s -> %s'
162 fmt = '%-'+str(size)+'s -> %s'
160 get = db.get
163 get = db.get
161 for var in vars:
164 for var in vars:
162 justkey = os.path.basename(var)
165 justkey = os.path.basename(var)
163 # print 30 first characters from every var
166 # print 30 first characters from every var
164 print fmt % (justkey, repr(get(var, '<unavailable>'))[:50])
167 print fmt % (justkey, repr(get(var, '<unavailable>'))[:50])
165
168
166 # default action - store the variable
169 # default action - store the variable
167 else:
170 else:
168 # %store foo >file.txt or >>file.txt
171 # %store foo >file.txt or >>file.txt
169 if len(args) > 1 and args[1].startswith('>'):
172 if len(args) > 1 and args[1].startswith('>'):
170 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
173 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
171 if args[1].startswith('>>'):
174 if args[1].startswith('>>'):
172 fil = open(fnam, 'a')
175 fil = open(fnam, 'a')
173 else:
176 else:
174 fil = open(fnam, 'w')
177 fil = open(fnam, 'w')
175 obj = ip.ev(args[0])
178 obj = ip.ev(args[0])
176 print "Writing '%s' (%s) to file '%s'." % (args[0],
179 print "Writing '%s' (%s) to file '%s'." % (args[0],
177 obj.__class__.__name__, fnam)
180 obj.__class__.__name__, fnam)
178
181
179
182
180 if not isinstance (obj, basestring):
183 if not isinstance (obj, basestring):
181 from pprint import pprint
184 from pprint import pprint
182 pprint(obj, fil)
185 pprint(obj, fil)
183 else:
186 else:
184 fil.write(obj)
187 fil.write(obj)
185 if not obj.endswith('\n'):
188 if not obj.endswith('\n'):
186 fil.write('\n')
189 fil.write('\n')
187
190
188 fil.close()
191 fil.close()
189 return
192 return
190
193
191 # %store foo
194 # %store foo
192 try:
195 try:
193 obj = ip.user_ns[args[0]]
196 obj = ip.user_ns[args[0]]
194 except KeyError:
197 except KeyError:
195 # it might be an alias
198 # it might be an alias
196 # This needs to be refactored to use the new AliasManager stuff.
199 # This needs to be refactored to use the new AliasManager stuff.
197 if args[0] in ip.alias_manager:
200 if args[0] in ip.alias_manager:
198 name = args[0]
201 name = args[0]
199 nargs, cmd = ip.alias_manager.alias_table[ name ]
202 nargs, cmd = ip.alias_manager.alias_table[ name ]
200 staliases = db.get('stored_aliases',{})
203 staliases = db.get('stored_aliases',{})
201 staliases[ name ] = cmd
204 staliases[ name ] = cmd
202 db['stored_aliases'] = staliases
205 db['stored_aliases'] = staliases
203 print "Alias stored: %s (%s)" % (name, cmd)
206 print "Alias stored: %s (%s)" % (name, cmd)
204 return
207 return
205 else:
208 else:
206 raise UsageError("Unknown variable '%s'" % args[0])
209 raise UsageError("Unknown variable '%s'" % args[0])
207
210
208 else:
211 else:
209 if isinstance(inspect.getmodule(obj), FakeModule):
212 if isinstance(inspect.getmodule(obj), FakeModule):
210 print textwrap.dedent("""\
213 print textwrap.dedent("""\
211 Warning:%s is %s
214 Warning:%s is %s
212 Proper storage of interactively declared classes (or instances
215 Proper storage of interactively declared classes (or instances
213 of those classes) is not possible! Only instances
216 of those classes) is not possible! Only instances
214 of classes in real modules on file system can be %%store'd.
217 of classes in real modules on file system can be %%store'd.
215 """ % (args[0], obj) )
218 """ % (args[0], obj) )
216 return
219 return
217 #pickled = pickle.dumps(obj)
220 #pickled = pickle.dumps(obj)
218 db[ 'autorestore/' + args[0] ] = obj
221 db[ 'autorestore/' + args[0] ] = obj
219 print "Stored '%s' (%s)" % (args[0], obj.__class__.__name__)
222 print "Stored '%s' (%s)" % (args[0], obj.__class__.__name__)
220
223
221
224
222 def load_ipython_extension(ip):
225 def load_ipython_extension(ip):
223 """Load the extension in IPython."""
226 """Load the extension in IPython."""
224 ip.register_magics(StoreMagics)
227 ip.register_magics(StoreMagics)
General Comments 0
You need to be logged in to leave comments. Login now