Merge lp:~fdo.perez/ipython/trunk-dev into lp:ipython/0.11

Proposed by Fernando Perez on 2009-03-13
Status: Merged
Merged at revision: not available
Proposed branch: lp:~fdo.perez/ipython/trunk-dev
Merge into: lp:ipython/0.11
Diff against target: None lines
To merge this branch: bzr merge lp:~fdo.perez/ipython/trunk-dev
Reviewer Review Type Date Requested Status
Brian Granger 2009-03-13 Needs Fixing on 2009-03-16
Review via email: mp+4450@code.launchpad.net
To post a comment you must log in.
Fernando Perez (fdo.perez) wrote :

I had to nuke my lp copy of my trunk because I did some local patch reordering, so I've just re-uploaded a fresh copy. The code is the same as before.

Ready for review.

lp:~fdo.perez/ipython/trunk-dev updated on 2009-03-16
1172. By Fernando Perez on 2009-03-14

Close https://bugs.launchpad.net/ipython/+bug/341726

Apply patch submitted by Alexander Clausen <alex-AT-gc-web.de>. Fixes
incorrect bug reporting URL for IPython and stale SVN references.

1173. By Fernando Perez on 2009-03-14

Fix https://bugs.launchpad.net/ipython/+bug/239054

- Made a more robust reset method to fully flush internal state and restore
the system to a clean state. We'll need to see later if %reset should just
call this. For now it's used to release resources.

1174. By Fernando Perez on 2009-03-14

Fix https://bugs.launchpad.net/ipython/+bug/284660

Since we now require python 2.4, I applied a simpler version of the patch
mentioned there, simply using the set() builtin everywhere.

1175. By Fernando Perez on 2009-03-15

Merging from upstream (with a few local cleanups when resolving conflicts).

1176. By Fernando Perez on 2009-03-15

Add a note about the conflict winpdb causes with PyTables.

1177. By Fernando Perez on 2009-03-16

Fix problems with multiline doctests and add docs about testing.

Also enabled some more testings that were blacklisted, now that the testing
machinery is more robust.

Brian Granger (ellisonbg) wrote :

I just had fun doing this code review. Launchpad has really improved its code review interface. I really like how you can look through the diffs for each file now!

One general comment: I know you like to code in a single branch, but it makes it more difficult to review a branch when there are many revisions on a wide range of topics. I don't think each revision should go in its own branch, but when there is a larger set of revisions addressing a single issue, having all of those revisions in a single topic branch would be nice and make review easier. Also, smaller branches allow code that *is* finished to get into trunk faster without waiting for unrelated code to be finished and reviewed. I am guilty of the "big branch" workflow myself though.

r1168:

As you go through file and clean up the copyright info, please convert the copyright header to our standard one that references the ipython development team. Any specific mention of module authors or maintainers should go into the module docstring.

r1169:

Are the numpy helper scripts for converting docstrings in place and working with our IPython?

How do we want to handle references in our docs. Sphinx can now create a nice references section in the pdf files, but you have to use a particular format for the references. The current form of the references you have put in::

    .. _PEP 257: http://www.python.org/peps/pep-0257.html

I don't think will end up in the references section. How does numpy handle such things. Have a look at how references are handled in the kernel documentation to see how I have been handling this. My way may not be the best. Let's figure out how all of us should handle this and then document it in our docs.

r1171:

In ipy_profile_zope.py. Should we just remove all the old __author__, etc. module attributes?

All other revisions are great.

review: Needs Fixing
lp:~fdo.perez/ipython/trunk-dev updated on 2009-03-17
1178. By Fernando Perez on 2009-03-16

Merging upstream changes from trunk (after fixing small conflicts).

Fernando Perez (fdo.perez) wrote :
Download full text (3.2 KiB)

Hey,

I know we talked offline about most of this, but I'll leave things
here for recording purposes.

On Mon, Mar 16, 2009 at 9:39 AM, Brian Granger <email address hidden> wrote:
> Review: Needs Fixing
> I just had fun doing this code review.  Launchpad has really improved its code review interface.  I really like how you can look through the diffs for each file now!

Yes, it's gotten much better. Launchpad is slowly but surely improving.

>
> One general comment:  I know you like to code in a single branch, but it makes it more difficult to review a branch when there are many revisions on a wide range of topics.  I don't think each revision should go in its own branch, but when there is a larger set of revisions addressing a single issue, having all of those revisions in a single topic branch would be nice and make review easier.  Also, smaller branches allow code that *is* finished to get into trunk faster without waiting for unrelated code to be finished and reviewed.  I am guilty of the "big branch" workflow myself though.

Me too, it's certainly a bad habit. As we spoke about, we could
probably settle on a workflow with:

- per-person permanent 'trunk-dev' branches, on which we do easy,
incremental reviewing and merging.
- short-lived 'feature branches' for standalone ideas, more like a
patch in other workflows, just a patch that keeps evolving and that's
easy to track as it changes.

I'll try to do better in the future on this, and I really appreciate
that you took the time to go over this much code. Many thanks.

>
> r1168:
>
> As you go through file and clean up the copyright info, please convert the copyright header to our standard one that references the ipython development team. Any specific mention of module authors or maintainers should go into the module docstring.

As I mentioned, I was really going after the 'import Release'
statements, not after the authorship notices. But from now on, I'll
try to cleanup the copyright notices as I work on files.

> r1169:
>
> Are the numpy helper scripts for converting docstrings in place and working with our IPython?
>
> How do we want to handle references in our docs.  Sphinx can now create a nice references section in the pdf files, but you have to use a particular format for the references.  The current form of the references you have put in::
>
>    .. _PEP 257: http://www.python.org/peps/pep-0257.html
>
> I don't think will end up in the references section.  How does numpy handle such things.  Have a look at how references are handled in the kernel documentation to see how I have been handling this.  My way may not be the best.  Let's figure out how all of us should handle this and then document it in our docs.

This one, I don't know. I'm going to look into what Matthew Brett did
for Nipy to see if I can find a good overall solution.

> r1171:
>
> In ipy_profile_zope.py.  Should we just remove all the old __author__, etc. module attributes?

I'll do what we discussed: put the authorship notes I find in the
top-level docstring. This has the added benefit of putting them in
the generated API docs.

> All other revisions are great.

Thanks again for reviewing such a monster!

I'l...

Read more...

lp:~fdo.perez/ipython/trunk-dev updated on 2009-03-17
1179. By Fernando Perez on 2009-03-17

Merging from upstream trunk

1180. By Fernando Perez on 2009-03-17

Update copyright/author statements.

- Updated copyright statements to use the new form:

# Copyright (C) 2008-2009 The IPython Development Team

I left the old notices in place (just updating the year in some cases),
because as far as I know, old copyright statements are not meant to be
retroactively modified.

- Also, on most files, replaced __author__ marks with an 'Authors' section
in the module docstring. This reduces top-level code in the module, while
ensuring that the Author(s) get properly acknowledged in auto-generated API
docs (sphinx doesn't read __author__ marks, but it will include the module
docstring).

I only left a few in place for very old files that we ship externally, and
for those by Laurent: he had his authorship mark both in the docstring and
in __author__ variables, so I think out of courtesy it would be better to
ask him about it on the list. All the others were I found regular
__author__ variables, I moved them to the main docstring.

Fernando Perez (fdo.perez) wrote :

"""
> r1168:
>
> As you go through file and clean up the copyright info, please convert the copyright header to our standard one that references the ipython development team. Any specific mention of module authors or maintainers should go into the module docstring.

As I mentioned, I was really going after the 'import Release'
statements, not after the authorship notices. But from now on, I'll
try to cleanup the copyright notices as I work on files.
"""

I did try to update at least those where I went fixing __author__ marks, as per your other comment. See the log comment in
http://bazaar.launchpad.net/~fdo.perez/ipython/trunk-dev/revision/1180
for more details on the logic I used. I took the 'team' 2008 statement and pushed to 09, and just closed the year gap on the old statements but otherwise left them as they were. I think that's how copyright statements are supposed to be updated, but I'm not sure. Feel free to let me know if it should be done otherwise.

> r1169:
>
> Are the numpy helper scripts for converting docstrings in place and working with our IPython?

Yes, they are. I've started using numpy docstrings in all new functions, and they work fine. I haven't gone updating old ones though... I did add mention of this in the dev docs.

"""
> How do we want to handle references in our docs.  Sphinx can now create a nice references section in the pdf files, but you have to use a particular format for the references.  The current form of the references you have put in::
>
>    .. _PEP 257: http://www.python.org/peps/pep-0257.html
>
> I don't think will end up in the references section.  How does numpy handle such things.  Have a look at how references are handled in the kernel documentation to see how I have been handling this.  My way may not be the best.  Let's figure out how all of us should handle this and then document it in our docs.

This one, I don't know. I'm going to look into what Matthew Brett did
for Nipy to see if I can find a good overall solution.
"""

I have to admit that I'm stumped on how to handle this one. Since it's not anything new in this branch per se, are you OK with merging and working on it together on trunk? I'm happy to make any local changes to the branch before merging, but I don't have a full solution for the references problem.

"""
> r1171:
>
> In ipy_profile_zope.py.  Should we just remove all the old __author__, etc. module attributes?

I'll do what we discussed: put the authorship notes I find in the
top-level docstring. This has the added benefit of putting them in
the generated API docs.
"""

I did go through most, as noted in the changelog. There's only a few left of very old external files, and Laurent's, which we should ask him about on list.

Thanks for the review!

lp:~fdo.perez/ipython/trunk-dev updated on 2009-03-17
1181. By Fernando Perez on 2009-03-17

Add information about our testing system, test writing tips, etc.

Brian Granger (ellisonbg) wrote :

> I did try to update at least those where I went fixing __author__ marks, as per your other comment.  See the log comment in
> http://bazaar.launchpad.net/~fdo.perez/ipython/trunk-dev/revision/1180
> for more details on the logic I used.  I took the 'team' 2008 statement and pushed to 09, and just closed the year gap on the old statements but otherwise left them as they were.   I think that's how copyright statements are supposed to be updated, but I'm not sure.  Feel free to let me know if it should be done otherwise.

Sounds fine by me.

>> r1169:
>>
>> Are the numpy helper scripts for converting docstrings in place and working with our IPython?
>
> Yes, they are.  I've started using numpy docstrings in all new functions, and they work fine.  I haven't gone updating old ones though...  I did add mention of this in the dev docs.

Great, I will start to write my docstring to this format.

>> How do we want to handle references in our docs.  Sphinx can now create a nice references section in the pdf files, but you have to use a particular format for the references.  The current form of the references you have put in::
>>
>>    .. _PEP 257: http://www.python.org/peps/pep-0257.html
>>
>> I don't think will end up in the references section.  How does numpy handle such things.  Have a look at how references are handled in the kernel documentation to see how I have been handling this.  My way may not be the best.  Let's figure out how all of us should handle this and then document it in our docs.
>
>
> This one, I don't know. I'm going to look into what Matthew Brett did
> for Nipy to see if I can find a good overall solution.
> """
>
> I have to admit that I'm stumped on how to handle this one.  Since it's not anything new in this branch per se, are you OK with merging and working on it together on trunk?  I'm happy to make any local changes to the branch before merging, but I don't have a full solution for the references problem.

That is fine. Just do the merge and we can slowly figure this one out.
 It is not a big deal because our existing refs don't do anything in
particular in this area, so we will have to change things anyway.

> Thanks for the review!

No problem.

Brian

--
Brian E. Granger, Ph.D.
Assistant Professor of Physics
Cal Poly State University, San Luis Obispo
<email address hidden>
<email address hidden>

lp:~fdo.perez/ipython/trunk-dev updated on 2009-03-17
1182. By Fernando Perez on 2009-03-17

Add a .bzrignore file for cleaner 'bzr status' output

Fernando Perez (fdo.perez) wrote :

On Tue, Mar 17, 2009 at 7:15 AM, Brian Granger <email address hidden> wrote:

> That is fine. Just do the merge and we can slowly figure this one out.
>  It is not a big deal because our existing refs don't do anything in
> particular in this area, so we will have to change things anyway.

OK. I just did the merge, this is large enough that I'll put a
message on the list so everyone can test it.

Thanks again for the review work, this one was a lot to look at :)

Cheers,

f

Preview Diff

1=== modified file 'IPython/ColorANSI.py'
2--- IPython/ColorANSI.py 2008-08-28 22:00:22 +0000
3+++ IPython/ColorANSI.py 2009-03-11 06:53:19 +0000
4@@ -1,7 +1,6 @@
5 # -*- coding: utf-8 -*-
6 """Tools for coloring text in ANSI terminals.
7-
8-$Id: ColorANSI.py 2167 2007-03-21 06:57:50Z fperez $"""
9+"""
10
11 #*****************************************************************************
12 # Copyright (C) 2002-2006 Fernando Perez. <fperez@colorado.edu>
13@@ -10,10 +9,6 @@
14 # the file COPYING, distributed as part of this software.
15 #*****************************************************************************
16
17-from IPython import Release
18-__author__ = '%s <%s>' % Release.authors['Fernando']
19-__license__ = Release.license
20-
21 __all__ = ['TermColors','InputTermColors','ColorScheme','ColorSchemeTable']
22
23 import os
24
25=== modified file 'IPython/ConfigLoader.py'
26--- IPython/ConfigLoader.py 2008-02-28 18:21:11 +0000
27+++ IPython/ConfigLoader.py 2009-03-11 06:53:19 +0000
28@@ -1,7 +1,6 @@
29 # -*- coding: utf-8 -*-
30 """Configuration loader
31-
32-$Id: ConfigLoader.py 1005 2006-01-12 08:39:26Z fperez $"""
33+"""
34
35 #*****************************************************************************
36 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
37@@ -10,10 +9,6 @@
38 # the file COPYING, distributed as part of this software.
39 #*****************************************************************************
40
41-from IPython import Release
42-__author__ = '%s <%s>' % Release.authors['Fernando']
43-__license__ = Release.license
44-
45 import exceptions
46 import os
47 from pprint import pprint
48@@ -73,14 +68,14 @@
49 # avoid including the same file more than once
50 if fname in self.included:
51 return data
52- Xinfo = ultraTB.AutoFormattedTB()
53+ Xinfo = ultraTB.AutoFormattedTB(color_scheme='NoColor')
54 if convert==None and recurse_key : convert = {qwflat:recurse_key}
55 # for production, change warn to 0:
56 data.merge(read_dict(fname,convert,fs=self.field_sep,strip=1,
57 warn=0,no_empty=0,**kw))
58 # keep track of successfully loaded files
59 self.included.append(fname)
60- if recurse_key in data.keys():
61+ if recurse_key in data:
62 for incfilename in data[recurse_key]:
63 found=0
64 try:
65
66=== modified file 'IPython/CrashHandler.py'
67--- IPython/CrashHandler.py 2008-02-28 18:21:11 +0000
68+++ IPython/CrashHandler.py 2009-03-11 06:53:19 +0000
69@@ -1,7 +1,6 @@
70 # -*- coding: utf-8 -*-
71 """sys.excepthook for IPython itself, leaves a detailed report on disk.
72-
73-$Id: CrashHandler.py 2908 2007-12-30 21:07:46Z vivainio $"""
74+"""
75
76 #*****************************************************************************
77 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
78
79=== modified file 'IPython/DPyGetOpt.py'
80--- IPython/DPyGetOpt.py 2008-02-28 18:21:11 +0000
81+++ IPython/DPyGetOpt.py 2009-03-11 06:53:19 +0000
82@@ -1,8 +1,6 @@
83 # -*- coding: utf-8 -*-
84 """DPyGetOpt -- Demiurge Python GetOptions Module
85
86- $Id: DPyGetOpt.py 2872 2007-11-25 17:58:05Z fperez $
87-
88 This module is modeled after perl's Getopt::Long module-- which
89 is, in turn, modeled after GNU's extended getopt() function.
90
91@@ -32,8 +30,7 @@
92 and -baz options that appear on within the parsed argument list
93 must have a real number argument and that the accumulated list
94 of values will be available under the name 'foo'
95-
96-$Id: DPyGetOpt.py 2872 2007-11-25 17:58:05Z fperez $"""
97+"""
98
99 #*****************************************************************************
100 #
101
102=== modified file 'IPython/Debugger.py'
103--- IPython/Debugger.py 2008-06-07 06:50:18 +0000
104+++ IPython/Debugger.py 2009-03-11 06:53:19 +0000
105@@ -13,9 +13,7 @@
106 changes. Licensing should therefore be under the standard Python terms. For
107 details on the PSF (Python Software Foundation) standard license, see:
108
109-http://www.python.org/2.2.3/license.html
110-
111-$Id: Debugger.py 2913 2007-12-31 12:42:14Z vivainio $"""
112+http://www.python.org/2.2.3/license.html"""
113
114 #*****************************************************************************
115 #
116@@ -27,10 +25,6 @@
117 #
118 #*****************************************************************************
119
120-from IPython import Release
121-__author__ = '%s <%s>' % Release.authors['Fernando']
122-__license__ = 'Python'
123-
124 import bdb
125 import cmd
126 import linecache
127@@ -39,7 +33,7 @@
128
129 from IPython import PyColorize, ColorANSI, ipapi
130 from IPython.genutils import Term
131-from IPython.excolors import ExceptionColors
132+from IPython.excolors import exception_colors
133
134 # See if we can use pydb.
135 has_pydb = False
136@@ -210,7 +204,7 @@
137
138 # Create color table: we copy the default one from the traceback
139 # module and add a few attributes needed for debugging
140- self.color_scheme_table = ExceptionColors.copy()
141+ self.color_scheme_table = exception_colors()
142
143 # shorthands
144 C = ColorANSI.TermColors
145@@ -257,8 +251,7 @@
146
147 # Create color table: we copy the default one from the traceback
148 # module and add a few attributes needed for debugging
149- ExceptionColors.set_active_scheme(color_scheme)
150- self.color_scheme_table = ExceptionColors.copy()
151+ self.color_scheme_table = exception_colors()
152
153 # shorthands
154 C = ColorANSI.TermColors
155
156=== modified file 'IPython/Extensions/InterpreterExec.py'
157--- IPython/Extensions/InterpreterExec.py 2008-02-28 18:21:11 +0000
158+++ IPython/Extensions/InterpreterExec.py 2009-03-11 06:53:19 +0000
159@@ -4,8 +4,7 @@
160 We define a special input line filter to allow typing lines which begin with
161 '~', '/' or '.'. If one of those strings is encountered, it is automatically
162 executed.
163-
164-$Id: InterpreterExec.py 2724 2007-09-07 08:05:38Z fperez $"""
165+"""
166
167 #*****************************************************************************
168 # Copyright (C) 2004 W.J. van der Laan <gnufnork@hetdigitalegat.nl>
169@@ -15,11 +14,6 @@
170 # the file COPYING, distributed as part of this software.
171 #*****************************************************************************
172
173-from IPython import Release
174-__author__ = 'W.J. van der Laan <gnufnork@hetdigitalegat.nl>, '\
175- '%s <%s>' % Release.authors['Fernando']
176-__license__ = Release.license
177-
178 # TODO: deprecated
179 def prefilter_shell(self,line,continuation):
180 """Alternate prefilter, modified for shell-like functionality.
181
182=== modified file 'IPython/Extensions/clearcmd.py'
183--- IPython/Extensions/clearcmd.py 2008-02-16 09:50:47 +0000
184+++ IPython/Extensions/clearcmd.py 2009-03-10 19:39:05 +0000
185@@ -5,43 +5,65 @@
186 import gc
187 ip = IPython.ipapi.get()
188
189-
190 def clear_f(self,arg):
191 """ Clear various data (e.g. stored history data)
192
193+ %clear in - clear input history
194 %clear out - clear output history
195- %clear in - clear input history
196 %clear shadow_compress - Compresses shadow history (to speed up ipython)
197 %clear shadow_nuke - permanently erase all entries in shadow history
198 %clear dhist - clear dir history
199+ %clear array - clear only variables that are NumPy arrays
200+
201+ Examples:
202+
203+ In [1]: clear in
204+ Flushing input history
205+
206+ In [2]: clear shadow_compress
207+ Compressing shadow history
208+
209+ In [3]: clear shadow_nuke
210+ Erased all keys from shadow history
211+
212+ In [4]: clear dhist
213+ Clearing directory history
214 """
215
216 api = self.getapi()
217+ user_ns = self.user_ns # local lookup, heavily used
218+
219+
220 for target in arg.split():
221+
222 if target == 'out':
223- print "Flushing output cache (%d entries)" % len(api.user_ns['_oh'])
224+ print "Flushing output cache (%d entries)" % len(user_ns['_oh'])
225 self.outputcache.flush()
226+
227 elif target == 'in':
228 print "Flushing input history"
229- from IPython import iplib
230 pc = self.outputcache.prompt_count + 1
231 for n in range(1, pc):
232 key = '_i'+`n`
233+ user_ns.pop(key,None)
234 try:
235- del self.user_ns[key]
236+ del user_ns[key]
237 except: pass
238 # must be done in-place
239 self.input_hist[:] = ['\n'] * pc
240 self.input_hist_raw[:] = ['\n'] * pc
241+
242 elif target == 'array':
243+ # Support cleaning up numpy arrays
244 try:
245- pylab=ip.IP.pylab
246- for x in self.user_ns.keys():
247- if isinstance(self.user_ns[x],pylab.arraytype):
248- del self.user_ns[x]
249+ from numpy import ndarray
250+ # This must be done with items and not iteritems because we're
251+ # going to modify the dict in-place.
252+ for x,val in user_ns.items():
253+ if isinstance(val,ndarray):
254+ del user_ns[x]
255 except AttributeError:
256- print "Clear array only available in -pylab mode"
257- gc.collect()
258+ print "Clear array only works if Numpy is available."
259
260 elif target == 'shadow_compress':
261 print "Compressing shadow history"
262@@ -51,16 +73,15 @@
263 print "Erased all keys from shadow history "
264 for k in ip.db.keys('shadowhist/*'):
265 del ip.db[k]
266+
267 elif target == 'dhist':
268 print "Clearing directory history"
269- del ip.user_ns['_dh'][:]
270-
271-
272+ del user_ns['_dh'][:]
273+
274+ gc.collect()
275+
276+# Activate the extension
277 ip.expose_magic("clear",clear_f)
278 import ipy_completers
279 ipy_completers.quick_completer(
280- '%clear','in out shadow_nuke shadow_compress dhist')
281-
282-
283-
284-
285+ '%clear','in out shadow_nuke shadow_compress dhist')
286
287=== modified file 'IPython/Extensions/ext_rescapture.py'
288--- IPython/Extensions/ext_rescapture.py 2008-02-16 09:50:47 +0000
289+++ IPython/Extensions/ext_rescapture.py 2009-03-11 06:53:19 +0000
290@@ -6,9 +6,6 @@
291 var = %magic blah blah
292
293 var = !ls
294-
295-$Id: genutils.py 1077 2006-01-24 18:15:27Z vivainio $
296-
297 """
298
299 import IPython.ipapi
300
301=== modified file 'IPython/Extensions/ipy_profile_zope.py'
302--- IPython/Extensions/ipy_profile_zope.py 2008-02-16 09:50:47 +0000
303+++ IPython/Extensions/ipy_profile_zope.py 2009-03-13 17:56:47 +0000
304@@ -12,7 +12,6 @@
305
306 __author__ = """Stefan Eletzhofer <stefan.eletzhofer@inquant.de>"""
307 __docformat__ = 'plaintext'
308-__revision__ = "$Revision$"
309
310 from IPython import ipapi
311 from IPython import Release
312
313=== modified file 'IPython/Extensions/pspersistence.py'
314--- IPython/Extensions/pspersistence.py 2008-06-03 20:03:02 +0000
315+++ IPython/Extensions/pspersistence.py 2009-03-11 06:53:19 +0000
316@@ -3,8 +3,6 @@
317 %store magic for lightweight persistence.
318
319 Stores variables, aliases etc. in PickleShare database.
320-
321-$Id: iplib.py 1107 2006-01-30 19:02:20Z vivainio $
322 """
323
324 import IPython.ipapi
325
326=== modified file 'IPython/FakeModule.py'
327--- IPython/FakeModule.py 2008-02-28 18:21:11 +0000
328+++ IPython/FakeModule.py 2009-03-11 06:53:19 +0000
329@@ -4,8 +4,7 @@
330
331 Needed to allow pickle to correctly resolve namespaces during IPython
332 sessions.
333-
334-$Id: FakeModule.py 2754 2007-09-09 10:16:59Z fperez $"""
335+"""
336
337 #*****************************************************************************
338 # Copyright (C) 2002-2004 Fernando Perez. <fperez@colorado.edu>
339
340=== modified file 'IPython/Gnuplot2.py'
341--- IPython/Gnuplot2.py 2008-02-28 18:21:11 +0000
342+++ IPython/Gnuplot2.py 2009-03-11 06:53:19 +0000
343@@ -12,8 +12,7 @@
344 Gnuplot, so it should be safe to do:
345
346 import IPython.Gnuplot2 as Gnuplot
347-
348-$Id: Gnuplot2.py 1210 2006-03-13 01:19:31Z fperez $"""
349+"""
350
351 import cStringIO
352 import os
353
354=== modified file 'IPython/GnuplotInteractive.py'
355--- IPython/GnuplotInteractive.py 2008-02-28 18:21:11 +0000
356+++ IPython/GnuplotInteractive.py 2009-03-11 06:53:19 +0000
357@@ -9,8 +9,7 @@
358 See gphelp() below for details on the services offered by this module.
359
360 Inspired by a suggestion/request from Arnd Baecker.
361-
362-$Id: GnuplotInteractive.py 389 2004-10-09 07:59:30Z fperez $"""
363+"""
364
365 __all__ = ['Gnuplot','gp','gp_new','plot','plot2','splot','replot',
366 'hardcopy','gpdata','gpfile','gpstring','gpfunc','gpgrid',
367
368=== modified file 'IPython/GnuplotRuntime.py'
369--- IPython/GnuplotRuntime.py 2008-02-28 18:21:11 +0000
370+++ IPython/GnuplotRuntime.py 2009-03-11 06:53:19 +0000
371@@ -47,8 +47,7 @@
372 http://gnuplot-py.sourceforge.net/
373
374 Inspired by a suggestion/request from Arnd Baecker.
375-
376-$Id: GnuplotRuntime.py 389 2004-10-09 07:59:30Z fperez $"""
377+"""
378
379 __all__ = ['Gnuplot','gp','gp_new','Data','File','Func','GridData',
380 'pm3d_config','eps_fix_bbox']
381
382=== modified file 'IPython/Itpl.py'
383--- IPython/Itpl.py 2008-05-15 05:05:58 +0000
384+++ IPython/Itpl.py 2009-03-11 06:53:19 +0000
385@@ -27,7 +27,7 @@
386 import Itpl
387 sys.stdout = Itpl.filter()
388 f = "fancy"
389- print "Isn't this $f?"
390+ print "Is this not $f?"
391 print "Standard output has been replaced with a $sys.stdout object."
392 sys.stdout = Itpl.unfilter()
393 print "Okay, back $to $normal."
394@@ -43,9 +43,7 @@
395 print str(s)
396 foo = "bar"
397 print str(s)
398-
399-$Id: Itpl.py 2918 2007-12-31 14:34:47Z vivainio $
400-""" # ' -> close an open quote for stupid emacs
401+"""
402
403 #*****************************************************************************
404 #
405
406=== modified file 'IPython/Logger.py'
407--- IPython/Logger.py 2008-08-14 12:48:09 +0000
408+++ IPython/Logger.py 2009-03-11 06:53:19 +0000
409@@ -1,8 +1,6 @@
410 # -*- coding: utf-8 -*-
411 """
412 Logger class for IPython's logging facilities.
413-
414-$Id: Logger.py 2875 2007-11-26 08:37:39Z fperez $
415 """
416
417 #*****************************************************************************
418@@ -16,11 +14,6 @@
419 #****************************************************************************
420 # Modules and globals
421
422-from IPython import Release
423-__author__ = '%s <%s>\n%s <%s>' % \
424- ( Release.authors['Janko'] + Release.authors['Fernando'] )
425-__license__ = Release.license
426-
427 # Python standard modules
428 import glob
429 import os
430
431=== modified file 'IPython/Magic.py'
432--- IPython/Magic.py 2008-09-17 19:07:48 +0000
433+++ IPython/Magic.py 2009-03-13 17:56:19 +0000
434@@ -1,7 +1,6 @@
435 # -*- coding: utf-8 -*-
436 """Magic functions for InteractiveShell.
437-
438-$Id: Magic.py 2996 2008-01-30 06:31:39Z fperez $"""
439+"""
440
441 #*****************************************************************************
442 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
443@@ -14,11 +13,6 @@
444 #****************************************************************************
445 # Modules and globals
446
447-from IPython import Release
448-__author__ = '%s <%s>\n%s <%s>' % \
449- ( Release.authors['Janko'] + Release.authors['Fernando'] )
450-__license__ = Release.license
451-
452 # Python standard modules
453 import __builtin__
454 import bdb
455@@ -1050,10 +1044,33 @@
456 def magic_reset(self, parameter_s=''):
457 """Resets the namespace by removing all names defined by the user.
458
459- Input/Output history are left around in case you need them."""
460-
461- ans = self.shell.ask_yes_no(
462- "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
463+ Input/Output history are left around in case you need them.
464+
465+ Parameters
466+ ----------
467+ -y : force reset without asking for confirmation.
468+
469+ Examples
470+ --------
471+ In [6]: a = 1
472+
473+ In [7]: a
474+ Out[7]: 1
475+
476+ In [8]: 'a' in _ip.user_ns
477+ Out[8]: True
478+
479+ In [9]: %reset -f
480+
481+ In [10]: 'a' in _ip.user_ns
482+ Out[10]: False
483+ """
484+
485+ if parameter_s == '-f':
486+ ans = True
487+ else:
488+ ans = self.shell.ask_yes_no(
489+ "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
490 if not ans:
491 print 'Nothing done.'
492 return
493@@ -1063,7 +1080,7 @@
494
495 # Also flush the private list of module references kept for script
496 # execution protection
497- self.shell._user_main_modules[:] = []
498+ self.shell.clear_main_mod_cache()
499
500 def magic_logstart(self,parameter_s=''):
501 """Start logging anywhere in a session.
502@@ -1422,7 +1439,8 @@
503 return None
504
505 @testdec.skip_doctest
506- def magic_run(self, parameter_s ='',runner=None):
507+ def magic_run(self, parameter_s ='',runner=None,
508+ file_finder=get_py_filename):
509 """Run the named file inside IPython as a program.
510
511 Usage:\\
512@@ -1537,7 +1555,7 @@
513 mode='list',list_all=1)
514
515 try:
516- filename = get_py_filename(arg_lst[0])
517+ filename = file_finder(arg_lst[0])
518 except IndexError:
519 warn('you must provide at least a filename.')
520 print '\n%run:\n',OInspect.getdoc(self.magic_run)
521@@ -1573,10 +1591,13 @@
522 main_mod = FakeModule()
523 prog_ns = main_mod.__dict__
524 prog_ns['__name__'] = name
525+
526 # The shell MUST hold a reference to main_mod so after %run exits,
527 # the python deletion mechanism doesn't zero it out (leaving
528- # dangling references)
529- self.shell._user_main_modules.append(main_mod)
530+ # dangling references). However, we should drop old versions of
531+ # main_mod. There is now a proper API to manage this caching in
532+ # the main shell object, we use that.
533+ self.shell.cache_main_mod(main_mod)
534
535 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
536 # set the __file__ global in the script's namespace
537
538=== modified file 'IPython/OInspect.py'
539--- IPython/OInspect.py 2008-07-29 22:57:51 +0000
540+++ IPython/OInspect.py 2009-03-11 06:53:19 +0000
541@@ -5,8 +5,6 @@
542
543 Similar in spirit to the inspect module, but all calls take a name argument to
544 reference the name under which an object is being read.
545-
546-$Id: OInspect.py 2843 2007-10-15 21:22:32Z fperez $
547 """
548
549 #*****************************************************************************
550@@ -16,10 +14,6 @@
551 # the file COPYING, distributed as part of this software.
552 #*****************************************************************************
553
554-from IPython import Release
555-__author__ = '%s <%s>' % Release.authors['Fernando']
556-__license__ = Release.license
557-
558 __all__ = ['Inspector','InspectColors']
559
560 # stdlib modules
561
562=== modified file 'IPython/OutputTrap.py'
563--- IPython/OutputTrap.py 2008-02-28 18:21:11 +0000
564+++ IPython/OutputTrap.py 2009-03-11 06:53:19 +0000
565@@ -1,7 +1,6 @@
566 # -*- coding: utf-8 -*-
567 """Class to trap stdout and stderr and log them separately.
568-
569-$Id: OutputTrap.py 958 2005-12-27 23:17:51Z fperez $"""
570+"""
571
572 #*****************************************************************************
573 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
574@@ -10,10 +9,6 @@
575 # the file COPYING, distributed as part of this software.
576 #*****************************************************************************
577
578-from IPython import Release
579-__author__ = '%s <%s>' % Release.authors['Fernando']
580-__license__ = Release.license
581-
582 import exceptions
583 import sys
584 from cStringIO import StringIO
585
586=== modified file 'IPython/Prompts.py'
587--- IPython/Prompts.py 2008-02-28 18:21:11 +0000
588+++ IPython/Prompts.py 2009-03-11 06:53:19 +0000
589@@ -1,8 +1,7 @@
590 # -*- coding: utf-8 -*-
591 """
592 Classes for handling input/output prompts.
593-
594-$Id: Prompts.py 3026 2008-02-07 16:03:16Z vivainio $"""
595+"""
596
597 #*****************************************************************************
598 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
599
600=== modified file 'IPython/PyColorize.py'
601--- IPython/PyColorize.py 2008-08-23 22:34:55 +0000
602+++ IPython/PyColorize.py 2009-03-11 06:53:19 +0000
603@@ -1,34 +1,33 @@
604 # -*- coding: utf-8 -*-
605 """
606- Class and program to colorize python source code for ANSI terminals.
607-
608- Based on an HTML code highlighter by Jurgen Hermann found at:
609- http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52298
610-
611- Modifications by Fernando Perez (fperez@colorado.edu).
612-
613- Information on the original HTML highlighter follows:
614-
615- MoinMoin - Python Source Parser
616-
617- Title: Colorize Python source using the built-in tokenizer
618-
619- Submitter: Jurgen Hermann
620- Last Updated:2001/04/06
621-
622- Version no:1.2
623-
624- Description:
625-
626- This code is part of MoinMoin (http://moin.sourceforge.net/) and converts
627- Python source code to HTML markup, rendering comments, keywords,
628- operators, numeric and string literals in different colors.
629-
630- It shows how to use the built-in keyword, token and tokenize modules to
631- scan Python source code and re-emit it with no changes to its original
632- formatting (which is the hard part).
633-
634- $Id: PyColorize.py 2586 2007-08-06 19:30:09Z vivainio $"""
635+Class and program to colorize python source code for ANSI terminals.
636+
637+Based on an HTML code highlighter by Jurgen Hermann found at:
638+http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52298
639+
640+Modifications by Fernando Perez (fperez@colorado.edu).
641+
642+Information on the original HTML highlighter follows:
643+
644+MoinMoin - Python Source Parser
645+
646+Title: Colorize Python source using the built-in tokenizer
647+
648+Submitter: Jurgen Hermann
649+Last Updated:2001/04/06
650+
651+Version no:1.2
652+
653+Description:
654+
655+This code is part of MoinMoin (http://moin.sourceforge.net/) and converts
656+Python source code to HTML markup, rendering comments, keywords,
657+operators, numeric and string literals in different colors.
658+
659+It shows how to use the built-in keyword, token and tokenize modules to
660+scan Python source code and re-emit it with no changes to its original
661+formatting (which is the hard part).
662+"""
663
664 __all__ = ['ANSICodeColors','Parser']
665
666
667=== modified file 'IPython/Shell.py'
668--- IPython/Shell.py 2008-08-24 06:10:55 +0000
669+++ IPython/Shell.py 2009-03-11 06:53:19 +0000
670@@ -3,8 +3,7 @@
671
672 All the matplotlib support code was co-developed with John Hunter,
673 matplotlib's author.
674-
675-$Id: Shell.py 3024 2008-02-07 15:34:42Z darren.dale $"""
676+"""
677
678 #*****************************************************************************
679 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
680@@ -13,10 +12,6 @@
681 # the file COPYING, distributed as part of this software.
682 #*****************************************************************************
683
684-from IPython import Release
685-__author__ = '%s <%s>' % Release.authors['Fernando']
686-__license__ = Release.license
687-
688 # Code begins
689 # Stdlib imports
690 import __builtin__
691
692=== modified file 'IPython/UserConfig/ipythonrc'
693--- IPython/UserConfig/ipythonrc 2008-02-28 18:21:11 +0000
694+++ IPython/UserConfig/ipythonrc 2009-03-13 17:56:47 +0000
695@@ -1,5 +1,4 @@
696 # -*- Mode: Shell-Script -*- Not really, but shows comments correctly
697-# $Id: ipythonrc 2156 2007-03-19 02:32:19Z fperez $
698
699 #***************************************************************************
700 #
701
702=== modified file 'IPython/__init__.py'
703--- IPython/__init__.py 2008-08-02 09:05:40 +0000
704+++ IPython/__init__.py 2009-03-11 06:53:19 +0000
705@@ -25,9 +25,8 @@
706
707 iii - serve as an embeddable, ready to go interpreter for your own programs.
708
709-IPython requires Python 2.3 or newer.
710-
711-$Id: __init__.py 2399 2007-05-26 10:23:10Z vivainio $"""
712+IPython requires Python 2.4 or newer.
713+"""
714
715 #*****************************************************************************
716 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
717
718=== modified file 'IPython/background_jobs.py'
719--- IPython/background_jobs.py 2008-02-28 18:21:11 +0000
720+++ IPython/background_jobs.py 2009-03-11 06:53:19 +0000
721@@ -17,8 +17,6 @@
722
723 (although ultimately no code from this text was used, as IPython's system is a
724 separate implementation).
725-
726-$Id: background_jobs.py 994 2006-01-08 08:29:44Z fperez $
727 """
728
729 #*****************************************************************************
730@@ -28,10 +26,6 @@
731 # the file COPYING, distributed as part of this software.
732 #*****************************************************************************
733
734-from IPython import Release
735-__author__ = '%s <%s>' % Release.authors['Fernando']
736-__license__ = Release.license
737-
738 # Code begins
739 import sys
740 import threading
741
742=== modified file 'IPython/completer.py'
743--- IPython/completer.py 2008-08-21 09:42:55 +0000
744+++ IPython/completer.py 2009-03-11 01:24:53 +0000
745@@ -6,7 +6,6 @@
746 functionality specific to IPython, so this module will continue to live as an
747 IPython-specific utility.
748
749----------------------------------------------------------------------------
750 Original rlcompleter documentation:
751
752 This requires the latest extension to the readline module (the
753
754=== modified file 'IPython/deep_reload.py'
755--- IPython/deep_reload.py 2008-07-17 06:37:49 +0000
756+++ IPython/deep_reload.py 2009-03-11 06:53:19 +0000
757@@ -12,8 +12,7 @@
758 >>> __builtin__.dreload = deep_reload.reload
759
760 This code is almost entirely based on knee.py from the standard library.
761-
762-$Id: deep_reload.py 958 2005-12-27 23:17:51Z fperez $"""
763+"""
764
765 #*****************************************************************************
766 # Copyright (C) 2001 Nathaniel Gray <n8gray@caltech.edu>
767@@ -22,12 +21,6 @@
768 # the file COPYING, distributed as part of this software.
769 #*****************************************************************************
770
771-from IPython import Release # do it explicitly so pydoc can see it - pydoc bug
772-__author__ = '%s <%s>' % Release.authors['Nathan']
773-__license__ = Release.license
774-__version__ = "0.5"
775-__date__ = "21 August 2001"
776-
777 import __builtin__
778 import imp
779 import sys
780
781=== modified file 'IPython/excolors.py'
782--- IPython/excolors.py 2008-02-16 09:50:47 +0000
783+++ IPython/excolors.py 2009-03-13 17:56:47 +0000
784@@ -1,8 +1,7 @@
785 # -*- coding: utf-8 -*-
786 """
787 Color schemes for exception handling code in IPython.
788-
789-$Id: Prompts.py 638 2005-07-18 03:01:41Z fperez $"""
790+"""
791
792 #*****************************************************************************
793 # Copyright (C) 2005-2006 Fernando Perez <fperez@colorado.edu>
794@@ -11,99 +10,128 @@
795 # the file COPYING, distributed as part of this software.
796 #*****************************************************************************
797
798-from IPython import Release
799-__author__ = '%s <%s>' % Release.authors['Fernando']
800-__license__ = Release.license
801-__version__ = Release.version
802-
803 #****************************************************************************
804 # Required modules
805 from IPython.ColorANSI import ColorSchemeTable, TermColors, ColorScheme
806
807-ExceptionColors = ColorSchemeTable()
808-
809-# Populate it with color schemes
810-C = TermColors # shorthand and local lookup
811-ExceptionColors.add_scheme(ColorScheme(
812- 'NoColor',
813- # The color to be used for the top line
814- topline = C.NoColor,
815-
816- # The colors to be used in the traceback
817- filename = C.NoColor,
818- lineno = C.NoColor,
819- name = C.NoColor,
820- vName = C.NoColor,
821- val = C.NoColor,
822- em = C.NoColor,
823-
824- # Emphasized colors for the last frame of the traceback
825- normalEm = C.NoColor,
826- filenameEm = C.NoColor,
827- linenoEm = C.NoColor,
828- nameEm = C.NoColor,
829- valEm = C.NoColor,
830-
831- # Colors for printing the exception
832- excName = C.NoColor,
833- line = C.NoColor,
834- caret = C.NoColor,
835- Normal = C.NoColor
836- ))
837-
838-# make some schemes as instances so we can copy them for modification easily
839-ExceptionColors.add_scheme(ColorScheme(
840- 'Linux',
841- # The color to be used for the top line
842- topline = C.LightRed,
843-
844- # The colors to be used in the traceback
845- filename = C.Green,
846- lineno = C.Green,
847- name = C.Purple,
848- vName = C.Cyan,
849- val = C.Green,
850- em = C.LightCyan,
851-
852- # Emphasized colors for the last frame of the traceback
853- normalEm = C.LightCyan,
854- filenameEm = C.LightGreen,
855- linenoEm = C.LightGreen,
856- nameEm = C.LightPurple,
857- valEm = C.LightBlue,
858-
859- # Colors for printing the exception
860- excName = C.LightRed,
861- line = C.Yellow,
862- caret = C.White,
863- Normal = C.Normal
864- ))
865-
866-# For light backgrounds, swap dark/light colors
867-ExceptionColors.add_scheme(ColorScheme(
868- 'LightBG',
869- # The color to be used for the top line
870- topline = C.Red,
871-
872- # The colors to be used in the traceback
873- filename = C.LightGreen,
874- lineno = C.LightGreen,
875- name = C.LightPurple,
876- vName = C.Cyan,
877- val = C.LightGreen,
878- em = C.Cyan,
879-
880- # Emphasized colors for the last frame of the traceback
881- normalEm = C.Cyan,
882- filenameEm = C.Green,
883- linenoEm = C.Green,
884- nameEm = C.Purple,
885- valEm = C.Blue,
886-
887- # Colors for printing the exception
888- excName = C.Red,
889- #line = C.Brown, # brown often is displayed as yellow
890- line = C.Red,
891- caret = C.Normal,
892- Normal = C.Normal
893- ))
894+def exception_colors():
895+ """Return a color table with fields for exception reporting.
896+
897+ The table is an instance of ColorSchemeTable with schemes added for
898+ 'Linux', 'LightBG' and 'NoColor' and fields for exception handling filled
899+ in.
900+
901+ Examples:
902+
903+ >>> ec = exception_colors()
904+ >>> ec.active_scheme_name
905+ ''
906+ >>> print ec.active_colors
907+ None
908+
909+ Now we activate a color scheme:
910+ >>> ec.set_active_scheme('NoColor')
911+ >>> ec.active_scheme_name
912+ 'NoColor'
913+ >>> ec.active_colors.keys()
914+ ['em', 'caret', '__allownew', 'name', 'val', 'vName', 'Normal', 'normalEm',
915+ 'filename', 'linenoEm', 'excName', 'lineno', 'valEm', 'filenameEm',
916+ 'nameEm', 'line', 'topline']
917+ """
918+
919+ ex_colors = ColorSchemeTable()
920+
921+ # Populate it with color schemes
922+ C = TermColors # shorthand and local lookup
923+ ex_colors.add_scheme(ColorScheme(
924+ 'NoColor',
925+ # The color to be used for the top line
926+ topline = C.NoColor,
927+
928+ # The colors to be used in the traceback
929+ filename = C.NoColor,
930+ lineno = C.NoColor,
931+ name = C.NoColor,
932+ vName = C.NoColor,
933+ val = C.NoColor,
934+ em = C.NoColor,
935+
936+ # Emphasized colors for the last frame of the traceback
937+ normalEm = C.NoColor,
938+ filenameEm = C.NoColor,
939+ linenoEm = C.NoColor,
940+ nameEm = C.NoColor,
941+ valEm = C.NoColor,
942+
943+ # Colors for printing the exception
944+ excName = C.NoColor,
945+ line = C.NoColor,
946+ caret = C.NoColor,
947+ Normal = C.NoColor
948+ ))
949+
950+ # make some schemes as instances so we can copy them for modification easily
951+ ex_colors.add_scheme(ColorScheme(
952+ 'Linux',
953+ # The color to be used for the top line
954+ topline = C.LightRed,
955+
956+ # The colors to be used in the traceback
957+ filename = C.Green,
958+ lineno = C.Green,
959+ name = C.Purple,
960+ vName = C.Cyan,
961+ val = C.Green,
962+ em = C.LightCyan,
963+
964+ # Emphasized colors for the last frame of the traceback
965+ normalEm = C.LightCyan,
966+ filenameEm = C.LightGreen,
967+ linenoEm = C.LightGreen,
968+ nameEm = C.LightPurple,
969+ valEm = C.LightBlue,
970+
971+ # Colors for printing the exception
972+ excName = C.LightRed,
973+ line = C.Yellow,
974+ caret = C.White,
975+ Normal = C.Normal
976+ ))
977+
978+ # For light backgrounds, swap dark/light colors
979+ ex_colors.add_scheme(ColorScheme(
980+ 'LightBG',
981+ # The color to be used for the top line
982+ topline = C.Red,
983+
984+ # The colors to be used in the traceback
985+ filename = C.LightGreen,
986+ lineno = C.LightGreen,
987+ name = C.LightPurple,
988+ vName = C.Cyan,
989+ val = C.LightGreen,
990+ em = C.Cyan,
991+
992+ # Emphasized colors for the last frame of the traceback
993+ normalEm = C.Cyan,
994+ filenameEm = C.Green,
995+ linenoEm = C.Green,
996+ nameEm = C.Purple,
997+ valEm = C.Blue,
998+
999+ # Colors for printing the exception
1000+ excName = C.Red,
1001+ #line = C.Brown, # brown often is displayed as yellow
1002+ line = C.Red,
1003+ caret = C.Normal,
1004+ Normal = C.Normal,
1005+ ))
1006+
1007+ return ex_colors
1008+
1009+
1010+# For backwards compatibility, keep around a single global object. Note that
1011+# this should NOT be used, the factory function should be used instead, since
1012+# these objects are stateful and it's very easy to get strange bugs if any code
1013+# modifies the module-level object's state.
1014+ExceptionColors = exception_colors()
1015
1016=== modified file 'IPython/external/Itpl.py'
1017--- IPython/external/Itpl.py 2008-06-06 19:58:56 +0000
1018+++ IPython/external/Itpl.py 2009-03-11 06:53:19 +0000
1019@@ -27,7 +27,7 @@
1020 import Itpl
1021 sys.stdout = Itpl.filter()
1022 f = "fancy"
1023- print "Isn't this $f?"
1024+ print "Is this not $f?"
1025 print "Standard output has been replaced with a $sys.stdout object."
1026 sys.stdout = Itpl.unfilter()
1027 print "Okay, back $to $normal."
1028@@ -43,9 +43,7 @@
1029 print str(s)
1030 foo = "bar"
1031 print str(s)
1032-
1033-$Id: Itpl.py 2305 2007-05-04 05:34:42Z bgranger $
1034-""" # ' -> close an open quote for stupid emacs
1035+"""
1036
1037 #*****************************************************************************
1038 #
1039
1040=== modified file 'IPython/genutils.py'
1041--- IPython/genutils.py 2008-09-03 23:31:20 +0000
1042+++ IPython/genutils.py 2009-03-11 06:53:19 +0000
1043@@ -1,11 +1,9 @@
1044 # -*- coding: utf-8 -*-
1045-"""
1046-General purpose utilities.
1047+"""General purpose utilities.
1048
1049 This is a grab-bag of stuff I find useful in most programs I write. Some of
1050 these things are also convenient when working at the command line.
1051-
1052-$Id: genutils.py 2998 2008-01-31 10:06:04Z vivainio $"""
1053+"""
1054
1055 #*****************************************************************************
1056 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
1057@@ -14,10 +12,6 @@
1058 # the file COPYING, distributed as part of this software.
1059 #*****************************************************************************
1060
1061-from IPython import Release
1062-__author__ = '%s <%s>' % Release.authors['Fernando']
1063-__license__ = Release.license
1064-
1065 #****************************************************************************
1066 # required modules from the Python standard library
1067 import __main__
1068@@ -1234,11 +1228,11 @@
1069 def make_quoted_expr(s):
1070 """Return string s in appropriate quotes, using raw string if possible.
1071
1072- Effectively this turns string: cd \ao\ao\
1073- to: r"cd \ao\ao\_"[:-1]
1074-
1075- Note the use of raw string and padding at the end to allow trailing backslash.
1076-
1077+ XXX - example removed because it caused encoding errors in documentation
1078+ generation. We need a new example that doesn't contain invalid chars.
1079+
1080+ Note the use of raw string and padding at the end to allow trailing
1081+ backslash.
1082 """
1083
1084 tail = ''
1085
1086=== modified file 'IPython/history.py'
1087--- IPython/history.py 2008-09-13 08:39:54 +0000
1088+++ IPython/history.py 2008-11-10 00:15:00 +0000
1089@@ -1,5 +1,4 @@
1090 # -*- coding: utf-8 -*-
1091-
1092 """ History related magics and functionality """
1093
1094 # Stdlib imports
1095@@ -7,7 +6,7 @@
1096 import os
1097
1098 # IPython imports
1099-from IPython.genutils import Term, ask_yes_no
1100+from IPython.genutils import Term, ask_yes_no, warn
1101 import IPython.ipapi
1102
1103 def magic_history(self, parameter_s = ''):
1104@@ -47,8 +46,6 @@
1105 -f FILENAME: instead of printing the output to the screen, redirect it to
1106 the given file. The file is always overwritten, though IPython asks for
1107 confirmation first if it already exists.
1108-
1109-
1110 """
1111
1112 ip = self.api
1113@@ -62,31 +59,28 @@
1114 try:
1115 outfname = opts['f']
1116 except KeyError:
1117- outfile = Term.cout
1118+ outfile = Term.cout # default
1119 # We don't want to close stdout at the end!
1120 close_at_end = False
1121 else:
1122 if os.path.exists(outfname):
1123- ans = ask_yes_no("File %r exists. Overwrite?" % outfname)
1124- if not ans:
1125+ if not ask_yes_no("File %r exists. Overwrite?" % outfname):
1126 print 'Aborting.'
1127 return
1128- else:
1129- outfile = open(outfname,'w')
1130- close_at_end = True
1131-
1132-
1133- if opts.has_key('t'):
1134+
1135+ outfile = open(outfname,'w')
1136+ close_at_end = True
1137+
1138+ if 't' in opts:
1139 input_hist = shell.input_hist
1140- elif opts.has_key('r'):
1141+ elif 'r' in opts:
1142 input_hist = shell.input_hist_raw
1143 else:
1144 input_hist = shell.input_hist
1145-
1146-
1147+
1148 default_length = 40
1149 pattern = None
1150- if opts.has_key('g'):
1151+ if 'g' in opts:
1152 init = 1
1153 final = len(input_hist)
1154 parts = parameter_s.split(None,1)
1155@@ -138,13 +132,11 @@
1156 outfile.close()
1157
1158
1159-
1160 def magic_hist(self, parameter_s=''):
1161 """Alternate name for %history."""
1162 return self.magic_history(parameter_s)
1163
1164
1165-
1166 def rep_f(self, arg):
1167 r""" Repeat a command, or get command to input line for editing
1168
1169@@ -173,11 +165,9 @@
1170 %rep foo
1171
1172 Place the most recent line that has the substring "foo" to next input.
1173- (e.g. 'svn ci -m foobar').
1174-
1175+ (e.g. 'svn ci -m foobar').
1176 """
1177
1178-
1179 opts,args = self.parse_options(arg,'',mode='list')
1180 ip = self.api
1181 if not args:
1182@@ -206,7 +196,6 @@
1183 ip.set_next_input(str(h).rstrip())
1184 return
1185
1186-
1187 try:
1188 lines = self.extract_input_slices(args, True)
1189 print "lines",lines
1190@@ -215,7 +204,6 @@
1191 print "Not found in recent history:", args
1192
1193
1194-
1195 _sentinel = object()
1196
1197 class ShadowHist:
1198@@ -259,23 +247,12 @@
1199 if k == idx:
1200 return v
1201
1202-def test_shist():
1203- from IPython.Extensions import pickleshare
1204- db = pickleshare.PickleShareDB('~/shist')
1205- s = ShadowHist(db)
1206- s.add('hello')
1207- s.add('world')
1208- s.add('hello')
1209- s.add('hello')
1210- s.add('karhu')
1211- print "all",s.all()
1212- print s.get(2)
1213
1214 def init_ipython(ip):
1215+ import ipy_completers
1216+
1217 ip.expose_magic("rep",rep_f)
1218 ip.expose_magic("hist",magic_hist)
1219 ip.expose_magic("history",magic_history)
1220
1221- import ipy_completers
1222 ipy_completers.quick_completer('%hist' ,'-g -t -r -n')
1223-#test_shist()
1224
1225=== modified file 'IPython/hooks.py'
1226--- IPython/hooks.py 2008-06-07 06:50:18 +0000
1227+++ IPython/hooks.py 2009-03-11 06:53:19 +0000
1228@@ -31,8 +31,7 @@
1229
1230 You can then enable the functionality by doing 'import myiphooks'
1231 somewhere in your configuration files or ipython command line.
1232-
1233-$Id: hooks.py 2998 2008-01-31 10:06:04Z vivainio $"""
1234+"""
1235
1236 #*****************************************************************************
1237 # Copyright (C) 2005 Fernando Perez. <fperez@colorado.edu>
1238@@ -41,11 +40,7 @@
1239 # the file COPYING, distributed as part of this software.
1240 #*****************************************************************************
1241
1242-from IPython import Release
1243 from IPython import ipapi
1244-__author__ = '%s <%s>' % Release.authors['Fernando']
1245-__license__ = Release.license
1246-__version__ = Release.version
1247
1248 import os,bisect
1249 from genutils import Term,shell
1250
1251=== modified file 'IPython/ipapi.py'
1252--- IPython/ipapi.py 2008-08-13 06:05:45 +0000
1253+++ IPython/ipapi.py 2009-03-11 01:24:53 +0000
1254@@ -24,7 +24,6 @@
1255 personal configuration (as opposed to boilerplate ipythonrc-PROFILENAME
1256 stuff) in there.
1257
1258------------------------------------------------
1259 import IPython.ipapi
1260 ip = IPython.ipapi.get()
1261
1262
1263=== modified file 'IPython/iplib.py'
1264--- IPython/iplib.py 2008-08-14 12:50:55 +0000
1265+++ IPython/iplib.py 2009-03-13 17:56:19 +0000
1266@@ -2,10 +2,9 @@
1267 """
1268 IPython -- An enhanced Interactive Python
1269
1270-Requires Python 2.3 or newer.
1271+Requires Python 2.4 or newer.
1272
1273 This file contains all the classes and helper functions specific to IPython.
1274-
1275 """
1276
1277 #*****************************************************************************
1278@@ -27,12 +26,6 @@
1279 #****************************************************************************
1280 # Modules and globals
1281
1282-from IPython import Release
1283-__author__ = '%s <%s>\n%s <%s>' % \
1284- ( Release.authors['Janko'] + Release.authors['Fernando'] )
1285-__license__ = Release.license
1286-__version__ = Release.version
1287-
1288 # Python standard modules
1289 import __main__
1290 import __builtin__
1291@@ -342,15 +335,19 @@
1292 # code ran is deleted. Now that this object is a true module (needed
1293 # so docetst and other tools work correctly), the Python module
1294 # teardown mechanism runs over it, and sets to None every variable
1295- # present in that module. This means that later calls to functions
1296- # defined in the script (which have become interactively visible after
1297- # script exit) fail, because they hold references to objects that have
1298- # become overwritten into None. The only solution I see right now is
1299- # to protect every FakeModule used by %run by holding an internal
1300- # reference to it. This private list will be used for that. The
1301- # %reset command will flush it as well.
1302- self._user_main_modules = []
1303-
1304+ # present in that module. Top-level references to objects from the
1305+ # script survive, because the user_ns is updated with them. However,
1306+ # calling functions defined in the script that use other things from
1307+ # the script will fail, because the function's closure had references
1308+ # to the original objects, which are now all None. So we must protect
1309+ # these modules from deletion by keeping a cache. To avoid keeping
1310+ # stale modules around (we only need the one from the last run), we use
1311+ # a dict keyed with the full path to the script, so only the last
1312+ # version of the module is held in the cache. The %reset command will
1313+ # flush this cache. See the cache_main_mod() and clear_main_mod_cache()
1314+ # methods for details on use.
1315+ self._user_main_modules = {}
1316+
1317 # List of input with multi-line handling.
1318 # Fill its zero entry, user counter starts at 1
1319 self.input_hist = InputList(['\n'])
1320@@ -601,10 +598,6 @@
1321
1322 #TODO: remove this, redundant
1323 self.add_builtins()
1324-
1325-
1326-
1327-
1328 # end __init__
1329
1330 def var_expand(self,cmd,depth=0):
1331@@ -633,16 +626,15 @@
1332 """
1333 rc = self.rc
1334 try:
1335- self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")
1336+ self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")
1337 except exceptions.UnicodeDecodeError:
1338 print "Your ipythondir can't be decoded to unicode!"
1339 print "Please set HOME environment variable to something that"
1340 print r"only has ASCII characters, e.g. c:\home"
1341 print "Now it is",rc.ipythondir
1342 sys.exit()
1343- self.shadowhist = IPython.history.ShadowHist(self.db)
1344-
1345-
1346+ self.shadowhist = IPython.history.ShadowHist(self.db)
1347+
1348 def post_config_initialization(self):
1349 """Post configuration init method
1350
1351@@ -909,7 +901,6 @@
1352 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1353 'Control auto-activation of pdb at exceptions')
1354
1355-
1356 # These special functions get installed in the builtin namespace, to
1357 # provide programmatic (pure python) access to magics, aliases and system
1358 # calls. This is important for logging, user scripting, and more.
1359@@ -1139,7 +1130,8 @@
1360 inif = 'ipythonrc.ini'
1361 else:
1362 inif = 'ipythonrc'
1363- minimal_setup = {'ipy_user_conf.py' : 'import ipy_defaults', inif : '# intentionally left blank' }
1364+ minimal_setup = {'ipy_user_conf.py' : 'import ipy_defaults',
1365+ inif : '# intentionally left blank' }
1366 os.makedirs(ipythondir, mode = 0777)
1367 for f, cont in minimal_setup.items():
1368 open(ipythondir + '/' + f,'w').write(cont)
1369@@ -1298,7 +1290,6 @@
1370 finally:
1371 readline.read_history_file(self.histfile)
1372 return wrapper
1373-
1374
1375 def pre_readline(self):
1376 """readline hook to be used at the start of each line.
1377@@ -1396,7 +1387,59 @@
1378 if self.rc.quiet:
1379 return True
1380 return ask_yes_no(prompt,default)
1381-
1382+
1383+ def cache_main_mod(self,mod):
1384+ """Cache a main module.
1385+
1386+ When scripts are executed via %run, we must keep a reference to their
1387+ __main__ module (a FakeModule instance) around so that Python doesn't
1388+ clear it, rendering objects defined therein useless.
1389+
1390+ This method keeps said reference in a private dict, keyed by the
1391+ absolute path of the module object (which corresponds to the script
1392+ path). This way, for multiple executions of the same script we only
1393+ keep one copy of __main__ (the last one), thus preventing memory leaks
1394+ from old references while allowing the objects from the last execution
1395+ to be accessible.
1396+
1397+ Parameters
1398+ ----------
1399+ mod : a module object
1400+
1401+ Examples
1402+ --------
1403+
1404+ In [10]: import IPython
1405+
1406+ In [11]: _ip.IP.cache_main_mod(IPython)
1407+
1408+ In [12]: IPython.__file__ in _ip.IP._user_main_modules
1409+ Out[12]: True
1410+ """
1411+ self._user_main_modules[os.path.abspath(mod.__file__) ] = mod
1412+
1413+ def clear_main_mod_cache(self):
1414+ """Clear the cache of main modules.
1415+
1416+ Mainly for use by utilities like %reset.
1417+
1418+ Examples
1419+ --------
1420+
1421+ In [15]: import IPython
1422+
1423+ In [16]: _ip.IP.cache_main_mod(IPython)
1424+
1425+ In [17]: len(_ip.IP._user_main_modules) > 0
1426+ Out[17]: True
1427+
1428+ In [18]: _ip.IP.clear_main_mod_cache()
1429+
1430+ In [19]: len(_ip.IP._user_main_modules) == 0
1431+ Out[19]: True
1432+ """
1433+ self._user_main_modules.clear()
1434+
1435 def _should_recompile(self,e):
1436 """Utility routine for edit_syntax_error"""
1437
1438@@ -1552,8 +1595,6 @@
1439 self.set_completer()
1440 except KeyboardInterrupt:
1441 self.write("\nKeyboardInterrupt\n")
1442-
1443-
1444
1445 def mainloop(self,banner=None):
1446 """Creates the local namespace and starts the mainloop.
1447@@ -1576,7 +1617,9 @@
1448 try:
1449 self.interact(banner)
1450 #self.interact_with_readline()
1451- # XXX for testing of a readline-decoupled repl loop, call interact_with_readline above
1452+
1453+ # XXX for testing of a readline-decoupled repl loop, call
1454+ # interact_with_readline above
1455
1456 break
1457 except KeyboardInterrupt:
1458
1459=== modified file 'IPython/ipmaker.py'
1460--- IPython/ipmaker.py 2008-06-04 08:15:46 +0000
1461+++ IPython/ipmaker.py 2009-03-11 06:53:19 +0000
1462@@ -5,8 +5,7 @@
1463 Requires Python 2.1 or better.
1464
1465 This file contains the main make_IPython() starter function.
1466-
1467-$Id: ipmaker.py 2930 2008-01-11 07:03:11Z vivainio $"""
1468+"""
1469
1470 #*****************************************************************************
1471 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
1472
1473=== modified file 'IPython/ipstruct.py'
1474--- IPython/ipstruct.py 2008-08-02 09:07:37 +0000
1475+++ IPython/ipstruct.py 2009-03-11 06:53:19 +0000
1476@@ -1,7 +1,6 @@
1477 # -*- coding: utf-8 -*-
1478 """Mimic C structs with lots of extra functionality.
1479-
1480-$Id: ipstruct.py 1950 2006-11-28 19:15:35Z vivainio $"""
1481+"""
1482
1483 #*****************************************************************************
1484 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
1485@@ -10,10 +9,6 @@
1486 # the file COPYING, distributed as part of this software.
1487 #*****************************************************************************
1488
1489-from IPython import Release
1490-__author__ = '%s <%s>' % Release.authors['Fernando']
1491-__license__ = Release.license
1492-
1493 __all__ = ['Struct']
1494
1495 import types
1496@@ -163,8 +158,22 @@
1497 return self.__dict__[key]
1498
1499 def __contains__(self,key):
1500- """Allows use of the 'in' operator."""
1501- return self.__dict__.has_key(key)
1502+ """Allows use of the 'in' operator.
1503+
1504+ Examples:
1505+ >>> s = Struct(x=1)
1506+ >>> 'x' in s
1507+ True
1508+ >>> 'y' in s
1509+ False
1510+ >>> s[4] = None
1511+ >>> 4 in s
1512+ True
1513+ >>> s.z = None
1514+ >>> 'z' in s
1515+ True
1516+ """
1517+ return key in self.__dict__
1518
1519 def __iadd__(self,other):
1520 """S += S2 is a shorthand for S.merge(S2)."""
1521@@ -246,12 +255,13 @@
1522 Optionally, one or more key=value pairs can be given at the end for
1523 direct update."""
1524
1525- # The funny name __loc_data__ is to prevent a common variable name which
1526- # could be a fieled of a Struct to collide with this parameter. The problem
1527- # would arise if the function is called with a keyword with this same name
1528- # that a user means to add as a Struct field.
1529+ # The funny name __loc_data__ is to prevent a common variable name
1530+ # which could be a fieled of a Struct to collide with this
1531+ # parameter. The problem would arise if the function is called with a
1532+ # keyword with this same name that a user means to add as a Struct
1533+ # field.
1534 newdict = Struct.__make_dict(self,__loc_data__,**kw)
1535- for k,v in newdict.items():
1536+ for k,v in newdict.iteritems():
1537 self[k] = v
1538
1539 def merge(self,__loc_data__=None,__conflict_solve=None,**kw):
1540
1541=== modified file 'IPython/kernel/core/ultraTB.py'
1542--- IPython/kernel/core/ultraTB.py 2008-06-06 19:41:55 +0000
1543+++ IPython/kernel/core/ultraTB.py 2009-03-11 06:53:19 +0000
1544@@ -1,5 +1,4 @@
1545-# encoding: utf-8
1546-
1547+# -*- coding: utf-8 -*-
1548 """
1549 ultraTB.py -- Spice up your tracebacks!
1550
1551@@ -60,26 +59,15 @@
1552 You can implement other color schemes easily, the syntax is fairly
1553 self-explanatory. Please send back new schemes you develop to the author for
1554 possible inclusion in future releases.
1555-
1556-$Id: ultraTB.py 2480 2007-07-06 19:33:43Z fperez $"""
1557-
1558-__docformat__ = "restructuredtext en"
1559-
1560-#-------------------------------------------------------------------------------
1561-# Copyright (C) 2008 The IPython Development Team
1562+"""
1563+
1564+#*****************************************************************************
1565+# Copyright (C) 2001 Nathaniel Gray <n8gray@caltech.edu>
1566+# Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
1567 #
1568 # Distributed under the terms of the BSD License. The full license is in
1569 # the file COPYING, distributed as part of this software.
1570-#-------------------------------------------------------------------------------
1571-
1572-#-------------------------------------------------------------------------------
1573-# Imports
1574-#-------------------------------------------------------------------------------
1575-
1576-from IPython import Release
1577-__author__ = '%s <%s>\n%s <%s>' % (Release.authors['Nathan']+
1578- Release.authors['Fernando'])
1579-__license__ = Release.license
1580+#*****************************************************************************
1581
1582 # Required modules
1583 import inspect
1584@@ -104,7 +92,7 @@
1585 # Modified pdb which doesn't damage IPython's readline handling
1586 from IPython import Debugger, PyColorize
1587 from IPython.ipstruct import Struct
1588-from IPython.excolors import ExceptionColors
1589+from IPython.excolors import exception_colors
1590 from IPython.genutils import Term,uniq_stable,error,info
1591
1592 # Globals
1593@@ -141,11 +129,18 @@
1594 FIXED version with which we monkeypatch the stdlib to work around a bug."""
1595
1596 file = getsourcefile(object) or getfile(object)
1597- module = getmodule(object, file)
1598- if module:
1599- lines = linecache.getlines(file, module.__dict__)
1600+ # If the object is a frame, then trying to get the globals dict from its
1601+ # module won't work. Instead, the frame object itself has the globals
1602+ # dictionary.
1603+ globals_dict = None
1604+ if inspect.isframe(object):
1605+ # XXX: can this ever be false?
1606+ globals_dict = object.f_globals
1607 else:
1608- lines = linecache.getlines(file)
1609+ module = getmodule(object, file)
1610+ if module:
1611+ globals_dict = module.__dict__
1612+ lines = linecache.getlines(file, globals_dict)
1613 if not lines:
1614 raise IOError('could not get source code')
1615
1616@@ -202,11 +197,31 @@
1617 if sys.version_info[:2] >= (2,5):
1618 inspect.findsource = findsource
1619
1620+def fix_frame_records_filenames(records):
1621+ """Try to fix the filenames in each record from inspect.getinnerframes().
1622+
1623+ Particularly, modules loaded from within zip files have useless filenames
1624+ attached to their code object, and inspect.getinnerframes() just uses it.
1625+ """
1626+ fixed_records = []
1627+ for frame, filename, line_no, func_name, lines, index in records:
1628+ # Look inside the frame's globals dictionary for __file__, which should
1629+ # be better.
1630+ better_fn = frame.f_globals.get('__file__', None)
1631+ if isinstance(better_fn, str):
1632+ # Check the type just in case someone did something weird with
1633+ # __file__. It might also be None if the error occurred during
1634+ # import.
1635+ filename = better_fn
1636+ fixed_records.append((frame, filename, line_no, func_name, lines, index))
1637+ return fixed_records
1638+
1639+
1640 def _fixed_getinnerframes(etb, context=1,tb_offset=0):
1641 import linecache
1642 LNUM_POS, LINES_POS, INDEX_POS = 2, 4, 5
1643
1644- records = inspect.getinnerframes(etb, context)
1645+ records = fix_frame_records_filenames(inspect.getinnerframes(etb, context))
1646
1647 # If the error is at the console, don't build any context, since it would
1648 # otherwise produce 5 blank lines printed out (there is no file at the
1649@@ -299,7 +314,7 @@
1650 self.call_pdb = call_pdb
1651
1652 # Create color table
1653- self.color_scheme_table = ExceptionColors
1654+ self.color_scheme_table = exception_colors()
1655
1656 self.set_colors(color_scheme)
1657 self.old_scheme = color_scheme # save initial value for toggles
1658@@ -356,8 +371,8 @@
1659
1660 def __call__(self, etype, value, elist):
1661 Term.cout.flush()
1662- Term.cerr.flush()
1663 print >> Term.cerr, self.text(etype,value,elist)
1664+ Term.cerr.flush()
1665
1666 def text(self,etype, value, elist,context=5):
1667 """Return a color formatted string with the traceback info."""
1668@@ -424,7 +439,8 @@
1669
1670 Also lifted nearly verbatim from traceback.py
1671 """
1672-
1673+
1674+ have_filedata = False
1675 Colors = self.Colors
1676 list = []
1677 try:
1678@@ -438,8 +454,9 @@
1679 try:
1680 msg, (filename, lineno, offset, line) = value
1681 except:
1682- pass
1683+ have_filedata = False
1684 else:
1685+ have_filedata = True
1686 #print 'filename is',filename # dbg
1687 if not filename: filename = "<string>"
1688 list.append('%s File %s"%s"%s, line %s%d%s\n' % \
1689@@ -469,6 +486,12 @@
1690 Colors.Normal, s))
1691 else:
1692 list.append('%s\n' % str(stype))
1693+
1694+ # vds:>>
1695+ if have_filedata:
1696+ __IPYTHON__.hooks.synchronize_with_editor(filename, lineno, 0)
1697+ # vds:<<
1698+
1699 return list
1700
1701 def _some_str(self, value):
1702@@ -780,6 +803,15 @@
1703 for name in names:
1704 value = text_repr(getattr(evalue, name))
1705 exception.append('\n%s%s = %s' % (indent, name, value))
1706+
1707+ # vds: >>
1708+ if records:
1709+ filepath, lnum = records[-1][1:3]
1710+ #print "file:", str(file), "linenb", str(lnum) # dbg
1711+ filepath = os.path.abspath(filepath)
1712+ __IPYTHON__.hooks.synchronize_with_editor(filepath, lnum, 0)
1713+ # vds: <<
1714+
1715 # return all our info assembled as a single string
1716 return '%s\n\n%s\n%s' % (head,'\n'.join(frames),''.join(exception[0]) )
1717
1718@@ -834,8 +866,8 @@
1719 (etype, evalue, etb) = info or sys.exc_info()
1720 self.tb = etb
1721 Term.cout.flush()
1722- Term.cerr.flush()
1723 print >> Term.cerr, self.text(etype, evalue, etb)
1724+ Term.cerr.flush()
1725
1726 # Changed so an instance can just be called as VerboseTB_inst() and print
1727 # out the right info on its own.
1728@@ -845,7 +877,10 @@
1729 self.handler()
1730 else:
1731 self.handler((etype, evalue, etb))
1732- self.debugger()
1733+ try:
1734+ self.debugger()
1735+ except KeyboardInterrupt:
1736+ print "\nKeyboardInterrupt"
1737
1738 #----------------------------------------------------------------------------
1739 class FormattedTB(VerboseTB,ListTB):
1740@@ -953,14 +988,17 @@
1741 if out is None:
1742 out = Term.cerr
1743 Term.cout.flush()
1744- out.flush()
1745 if tb_offset is not None:
1746 tb_offset, self.tb_offset = self.tb_offset, tb_offset
1747 print >> out, self.text(etype, evalue, etb)
1748 self.tb_offset = tb_offset
1749 else:
1750 print >> out, self.text(etype, evalue, etb)
1751- self.debugger()
1752+ out.flush()
1753+ try:
1754+ self.debugger()
1755+ except KeyboardInterrupt:
1756+ print "\nKeyboardInterrupt"
1757
1758 def text(self,etype=None,value=None,tb=None,context=5,mode=None):
1759 if etype is None:
1760
1761=== modified file 'IPython/kernel/core/util.py'
1762--- IPython/kernel/core/util.py 2008-06-06 19:41:55 +0000
1763+++ IPython/kernel/core/util.py 2009-03-11 01:24:53 +0000
1764@@ -70,8 +70,8 @@
1765 def make_quoted_expr(s):
1766 """Return string s in appropriate quotes, using raw string if possible.
1767
1768- Effectively this turns string: cd \ao\ao\
1769- to: r"cd \ao\ao\_"[:-1]
1770+ XXX - example removed because it caused encoding errors in documentation
1771+ generation. We need a new example that doesn't contain invalid chars.
1772
1773 Note the use of raw string and padding at the end to allow trailing
1774 backslash.
1775
1776=== modified file 'IPython/kernel/scripts/ipcluster' (properties changed: -x to +x)
1777=== modified file 'IPython/kernel/scripts/ipcluster.py' (properties changed: -x to +x)
1778=== modified file 'IPython/kernel/scripts/ipcontroller' (properties changed: -x to +x)
1779=== modified file 'IPython/kernel/scripts/ipcontroller.py' (properties changed: -x to +x)
1780=== modified file 'IPython/kernel/scripts/ipengine' (properties changed: -x to +x)
1781=== modified file 'IPython/kernel/scripts/ipengine.py' (properties changed: -x to +x)
1782=== modified file 'IPython/macro.py'
1783--- IPython/macro.py 2008-02-16 09:50:47 +0000
1784+++ IPython/macro.py 2009-03-11 06:53:19 +0000
1785@@ -9,7 +9,6 @@
1786
1787 import IPython.ipapi
1788
1789-
1790 from IPython.genutils import Term
1791 from IPython.ipapi import IPyAutocall
1792
1793@@ -41,4 +40,4 @@
1794
1795 def __getstate__(self):
1796 """ needed for safe pickling via %store """
1797- return {'value': self.value}
1798\ No newline at end of file
1799+ return {'value': self.value}
1800
1801=== modified file 'IPython/numutils.py'
1802--- IPython/numutils.py 2008-02-28 18:21:11 +0000
1803+++ IPython/numutils.py 2009-03-11 06:53:19 +0000
1804@@ -4,8 +4,7 @@
1805
1806 Most of this module requires Numerical Python or is meant to be used with it.
1807 See http://www.pfdubois.com/numpy for details.
1808-
1809-$Id: numutils.py 958 2005-12-27 23:17:51Z fperez $"""
1810+"""
1811
1812 #*****************************************************************************
1813 # Copyright (C) 2001-2005 Fernando Perez <fperez@colorado.edu>
1814@@ -14,10 +13,6 @@
1815 # the file COPYING, distributed as part of this software.
1816 #*****************************************************************************
1817
1818-from IPython import Release
1819-__author__ = '%s <%s>' % Release.authors['Fernando']
1820-__license__ = Release.license
1821-
1822 __all__ = ['sum_flat','mean_flat','rms_flat','base_repr','binary_repr',
1823 'amin','amax','amap','zeros_like','empty_like',
1824 'frange','diagonal_matrix','identity',
1825
1826=== modified file 'IPython/platutils.py'
1827--- IPython/platutils.py 2008-07-06 16:54:20 +0000
1828+++ IPython/platutils.py 2009-03-11 06:27:38 +0000
1829@@ -12,10 +12,6 @@
1830 # the file COPYING, distributed as part of this software.
1831 #*****************************************************************************
1832
1833-from IPython import Release
1834-__author__ = '%s <%s>' % Release.authors['Ville']
1835-__license__ = Release.license
1836-
1837 import os
1838 import sys
1839
1840@@ -35,8 +31,26 @@
1841 # Functionality that's logically common to all platforms goes here, each
1842 # platform-specific module only provides the bits that are OS-dependent.
1843
1844-def freeze_term_title():
1845- _platutils.ignore_termtitle = True
1846+# XXX - I'm still not happy with a module global for this, but at least now
1847+# there is a public, cross-platform way of toggling the term title control on
1848+# and off. We should make this a stateful object later on so that each user
1849+# can have its own instance if needed.
1850+def toggle_set_term_title(val):
1851+ """Control whether set_term_title is active or not.
1852+
1853+ set_term_title() allows writing to the console titlebar. In embedded
1854+ widgets this can cause problems, so this call can be used to toggle it on
1855+ or off as needed.
1856+
1857+ The default state of the module is for the function to be disabled.
1858+
1859+ Parameters
1860+ ----------
1861+ val : bool
1862+ If True, set_term_title() actually writes to the terminal (using the
1863+ appropriate platform-specific module). If False, it is a no-op.
1864+ """
1865+ _platutils.ignore_termtitle = not(val)
1866
1867
1868 def set_term_title(title):
1869@@ -45,3 +59,12 @@
1870 if _platutils.ignore_termtitle:
1871 return
1872 _platutils.set_term_title(title)
1873+
1874+
1875+#-----------------------------------------------------------------------------
1876+# Deprecated functions
1877+#-----------------------------------------------------------------------------
1878+def freeze_term_title():
1879+ warnings.warn("This function is deprecated, use toggle_set_term_title()")
1880+ _platutils.ignore_termtitle = True
1881+
1882
1883=== modified file 'IPython/platutils_posix.py'
1884--- IPython/platutils_posix.py 2008-07-06 16:54:20 +0000
1885+++ IPython/platutils_posix.py 2009-03-11 06:27:38 +0000
1886@@ -12,14 +12,10 @@
1887 # the file COPYING, distributed as part of this software.
1888 #*****************************************************************************
1889
1890-from IPython import Release
1891-__author__ = '%s <%s>' % Release.authors['Ville']
1892-__license__ = Release.license
1893-
1894 import sys
1895 import os
1896
1897-ignore_termtitle = False
1898+ignore_termtitle = True
1899
1900 def _dummy_op(*a, **b):
1901 """ A no-op function """
1902@@ -27,7 +23,7 @@
1903 def _set_term_title_xterm(title):
1904 """ Change virtual terminal title in xterm-workalikes """
1905
1906- sys.stdout.write('\033]%d;%s\007' % (0,title))
1907+ sys.stdout.write('\033]0;%s\007' % title)
1908
1909
1910 if os.environ.get('TERM','') == 'xterm':
1911
1912=== modified file 'IPython/platutils_win32.py'
1913--- IPython/platutils_win32.py 2008-07-06 16:54:20 +0000
1914+++ IPython/platutils_win32.py 2009-03-11 06:53:19 +0000
1915@@ -12,13 +12,9 @@
1916 # the file COPYING, distributed as part of this software.
1917 #*****************************************************************************
1918
1919-from IPython import Release
1920-__author__ = '%s <%s>' % Release.authors['Ville']
1921-__license__ = Release.license
1922-
1923 import os
1924
1925-ignore_termtitle = False
1926+ignore_termtitle = True
1927
1928 try:
1929 import ctypes
1930
1931=== modified file 'IPython/rlineimpl.py'
1932--- IPython/rlineimpl.py 2008-02-16 09:50:47 +0000
1933+++ IPython/rlineimpl.py 2009-03-11 06:53:19 +0000
1934@@ -5,8 +5,7 @@
1935
1936 In addition to normal readline stuff, this module provides have_readline
1937 boolean and _outputfile variable used in genutils.
1938-
1939-$Id: Magic.py 1096 2006-01-28 20:08:02Z vivainio $"""
1940+"""
1941
1942 import sys
1943
1944@@ -53,4 +52,4 @@
1945 _rl.clear_history
1946 except AttributeError:
1947 def clear_history(): pass
1948- _rl.clear_history = clear_history
1949\ No newline at end of file
1950+ _rl.clear_history = clear_history
1951
1952=== modified file 'IPython/shellglobals.py'
1953--- IPython/shellglobals.py 2008-03-22 15:03:36 +0000
1954+++ IPython/shellglobals.py 2009-03-11 06:53:19 +0000
1955@@ -1,6 +1,13 @@
1956-from IPython.genutils import Term,warn,error,flag_calls, ask_yes_no
1957-
1958-import thread,inspect
1959+"""Some globals used by the main Shell classes.
1960+"""
1961+
1962+#-----------------------------------------------------------------------------
1963+# Module imports
1964+#-----------------------------------------------------------------------------
1965+
1966+# stdlib
1967+import inspect
1968+import thread
1969
1970 try:
1971 import ctypes
1972@@ -8,8 +15,12 @@
1973 except ImportError:
1974 HAS_CTYPES = False
1975
1976+# our own
1977+from IPython.genutils import Term,warn,error,flag_calls, ask_yes_no
1978
1979+#-----------------------------------------------------------------------------
1980 # Globals
1981+#-----------------------------------------------------------------------------
1982 # global flag to pass around information about Ctrl-C without exceptions
1983 KBINT = False
1984
1985@@ -22,13 +33,11 @@
1986 # Tag when runcode() is active, for exception handling
1987 CODE_RUN = None
1988
1989-
1990 #-----------------------------------------------------------------------------
1991 # This class is trivial now, but I want to have it in to publish a clean
1992 # interface. Later when the internals are reorganized, code that uses this
1993 # shouldn't have to change.
1994
1995-
1996 if HAS_CTYPES:
1997 # Add async exception support. Trick taken from:
1998 # http://sebulba.wikispaces.com/recipe+thread2
1999@@ -81,16 +90,12 @@
2000 # Set global flag so that runsource can know that Ctrl-C was hit
2001 KBINT = True
2002
2003+
2004 def run_in_frontend(src):
2005- """ Check if source snippet can be run in the REPL thread, as opposed to GUI mainloop
2006-
2007- (to prevent unnecessary hanging of mainloop).
2008-
2009+ """ Check if source snippet can be run in the REPL thread, as opposed to
2010+ GUI mainloop (to prevent unnecessary hanging of mainloop).
2011 """
2012
2013 if src.startswith('_ip.system(') and not '\n' in src:
2014 return True
2015 return False
2016-
2017-
2018-
2019
2020=== modified file 'IPython/strdispatch.py'
2021--- IPython/strdispatch.py 2008-07-30 20:08:19 +0000
2022+++ IPython/strdispatch.py 2009-03-11 06:53:19 +0000
2023@@ -8,7 +8,6 @@
2024 from IPython.hooks import CommandChainDispatcher
2025 import IPython.hooks
2026
2027-
2028 # Code begins
2029 class StrDispatch(object):
2030 """Dispatch (lookup) a set of strings / regexps for match.
2031
2032=== modified file 'IPython/testing/decorators.py'
2033--- IPython/testing/decorators.py 2008-09-15 02:07:52 +0000
2034+++ IPython/testing/decorators.py 2009-03-11 01:24:53 +0000
2035@@ -1,12 +1,10 @@
2036 """Decorators for labeling test objects.
2037
2038-Decorators that merely return a modified version of the original
2039-function object are straightforward. Decorators that return a new
2040-function object need to use
2041-nose.tools.make_decorator(original_function)(decorator) in returning
2042-the decorator, in order to preserve metadata such as function name,
2043-setup and teardown functions and so on - see nose.tools for more
2044-information.
2045+Decorators that merely return a modified version of the original function
2046+object are straightforward. Decorators that return a new function object need
2047+to use nose.tools.make_decorator(original_function)(decorator) in returning the
2048+decorator, in order to preserve metadata such as function name, setup and
2049+teardown functions and so on - see nose.tools for more information.
2050
2051 This module provides a set of useful decorators meant to be ready to use in
2052 your own tests. See the bottom of the file for the ready-made ones, and if you
2053@@ -115,6 +113,115 @@
2054
2055 return decor
2056
2057+
2058+# Inspired by numpy's skipif, but uses the full apply_wrapper utility to
2059+# preserve function metadata better and allows the skip condition to be a
2060+# callable.
2061+def skipif(skip_condition, msg=None):
2062+ ''' Make function raise SkipTest exception if skip_condition is true
2063+
2064+ Parameters
2065+ ----------
2066+ skip_condition : bool or callable.
2067+ Flag to determine whether to skip test. If the condition is a
2068+ callable, it is used at runtime to dynamically make the decision. This
2069+ is useful for tests that may require costly imports, to delay the cost
2070+ until the test suite is actually executed.
2071+ msg : string
2072+ Message to give on raising a SkipTest exception
2073+
2074+ Returns
2075+ -------
2076+ decorator : function
2077+ Decorator, which, when applied to a function, causes SkipTest
2078+ to be raised when the skip_condition was True, and the function
2079+ to be called normally otherwise.
2080+
2081+ Notes
2082+ -----
2083+ You will see from the code that we had to further decorate the
2084+ decorator with the nose.tools.make_decorator function in order to
2085+ transmit function name, and various other metadata.
2086+ '''
2087+
2088+ def skip_decorator(f):
2089+ # Local import to avoid a hard nose dependency and only incur the
2090+ # import time overhead at actual test-time.
2091+ import nose
2092+
2093+ # Allow for both boolean or callable skip conditions.
2094+ if callable(skip_condition):
2095+ skip_val = lambda : skip_condition()
2096+ else:
2097+ skip_val = lambda : skip_condition
2098+
2099+ def get_msg(func,msg=None):
2100+ """Skip message with information about function being skipped."""
2101+ if msg is None: out = 'Test skipped due to test condition.'
2102+ else: out = msg
2103+ return "Skipping test: %s. %s" % (func.__name__,out)
2104+
2105+ # We need to define *two* skippers because Python doesn't allow both
2106+ # return with value and yield inside the same function.
2107+ def skipper_func(*args, **kwargs):
2108+ """Skipper for normal test functions."""
2109+ if skip_val():
2110+ raise nose.SkipTest(get_msg(f,msg))
2111+ else:
2112+ return f(*args, **kwargs)
2113+
2114+ def skipper_gen(*args, **kwargs):
2115+ """Skipper for test generators."""
2116+ if skip_val():
2117+ raise nose.SkipTest(get_msg(f,msg))
2118+ else:
2119+ for x in f(*args, **kwargs):
2120+ yield x
2121+
2122+ # Choose the right skipper to use when building the actual generator.
2123+ if nose.util.isgenerator(f):
2124+ skipper = skipper_gen
2125+ else:
2126+ skipper = skipper_func
2127+
2128+ return nose.tools.make_decorator(f)(skipper)
2129+
2130+ return skip_decorator
2131+
2132+# A version with the condition set to true, common case just to attacha message
2133+# to a skip decorator
2134+def skip(msg=None):
2135+ """Decorator factory - mark a test function for skipping from test suite.
2136+
2137+ :Parameters:
2138+ msg : string
2139+ Optional message to be added.
2140+
2141+ :Returns:
2142+ decorator : function
2143+ Decorator, which, when applied to a function, causes SkipTest
2144+ to be raised, with the optional message added.
2145+ """
2146+
2147+ return skipif(True,msg)
2148+
2149+
2150+#-----------------------------------------------------------------------------
2151+# Utility functions for decorators
2152+def numpy_not_available():
2153+ """Can numpy be imported? Returns true if numpy does NOT import.
2154+
2155+ This is used to make a decorator to skip tests that require numpy to be
2156+ available, but delay the 'import numpy' to test execution time.
2157+ """
2158+ try:
2159+ import numpy
2160+ np_not_avail = False
2161+ except ImportError:
2162+ np_not_avail = True
2163+
2164+ return np_not_avail
2165+
2166 #-----------------------------------------------------------------------------
2167 # Decorators for public use
2168
2169@@ -125,36 +232,13 @@
2170 omit from testing, while preserving the docstring for introspection, help,
2171 etc.""")
2172
2173-def skip(msg=''):
2174- """Decorator - mark a test function for skipping from test suite.
2175-
2176- This function *is* already a decorator, it is not a factory like
2177- make_label_dec or some of those in decorators_numpy.
2178-
2179- :Parameters:
2180-
2181- func : function
2182- Test function to be skipped
2183-
2184- msg : string
2185- Optional message to be added.
2186- """
2187-
2188- import nose
2189-
2190- def inner(func):
2191-
2192- def wrapper(*a,**k):
2193- if msg: out = '\n'+msg
2194- else: out = ''
2195- raise nose.SkipTest("Skipping test for function: %s%s" %
2196- (func.__name__,out))
2197-
2198- return apply_wrapper(wrapper,func)
2199-
2200- return inner
2201-
2202 # Decorators to skip certain tests on specific platforms.
2203-skip_win32 = skipif(sys.platform=='win32',"This test does not run under Windows")
2204+skip_win32 = skipif(sys.platform=='win32',
2205+ "This test does not run under Windows")
2206 skip_linux = skipif(sys.platform=='linux2',"This test does not run under Linux")
2207-skip_osx = skipif(sys.platform=='darwin',"This test does not run under OSX")
2208+skip_osx = skipif(sys.platform=='darwin',"This test does not run under OS X")
2209+
2210+
2211+skipif_not_numpy = skipif(numpy_not_available,"This test requires numpy")
2212+
2213+skipknownfailure = skip('This test is known to fail')
2214
2215=== modified file 'IPython/testing/decorators_numpy.py'
2216--- IPython/testing/decorators_numpy.py 2008-08-02 09:07:37 +0000
2217+++ IPython/testing/decorators_numpy.py 2009-03-11 01:24:53 +0000
2218@@ -46,13 +46,16 @@
2219 return t
2220 return set_test
2221
2222-def skipif(skip_condition, msg=None):
2223+def skipif(skip_condition=True, msg=None):
2224 ''' Make function raise SkipTest exception if skip_condition is true
2225
2226 Parameters
2227- ---------
2228- skip_condition : bool
2229- Flag to determine whether to skip test (True) or not (False)
2230+ ----------
2231+ skip_condition : bool or callable.
2232+ Flag to determine whether to skip test. If the condition is a
2233+ callable, it is used at runtime to dynamically make the decision. This
2234+ is useful for tests that may require costly imports, to delay the cost
2235+ until the test suite is actually executed.
2236 msg : string
2237 Message to give on raising a SkipTest exception
2238
2239
2240=== modified file 'IPython/testing/iptest.py'
2241--- IPython/testing/iptest.py 2008-08-24 06:37:40 +0000
2242+++ IPython/testing/iptest.py 2009-03-11 05:49:08 +0000
2243@@ -1,16 +1,53 @@
2244-#!/usr/bin/env python
2245 # -*- coding: utf-8 -*-
2246 """IPython Test Suite Runner.
2247+
2248+This module provides a main entry point to a user script to test IPython itself
2249+from the command line. The main() routine can be used in a similar manner to
2250+the ``nosetests`` script, and it takes similar arguments, but if no arguments
2251+are given it defaults to testing all of IPython. This should be preferred to
2252+using plain ``nosetests`` because a number of nose plugins necessary to test
2253+IPython correctly are automatically configured by this code.
2254 """
2255
2256+#-----------------------------------------------------------------------------
2257+# Module imports
2258+#-----------------------------------------------------------------------------
2259+
2260+# stdlib
2261 import sys
2262 import warnings
2263
2264+# third-party
2265+import nose.plugins.builtin
2266 from nose.core import TestProgram
2267-import nose.plugins.builtin
2268
2269+# Our own imports
2270 from IPython.testing.plugin.ipdoctest import IPythonDoctest
2271
2272+#-----------------------------------------------------------------------------
2273+# Constants and globals
2274+#-----------------------------------------------------------------------------
2275+
2276+# For the IPythonDoctest plugin, we need to exclude certain patterns that cause
2277+# testing problems. We should strive to minimize the number of skipped
2278+# modules, since this means untested code. As the testing machinery
2279+# solidifies, this list should eventually become empty.
2280+EXCLUDE = ['IPython/external/',
2281+ 'IPython/platutils_win32',
2282+ 'IPython/frontend/cocoa',
2283+ 'IPython_doctest_plugin',
2284+ 'IPython/Gnuplot',
2285+ 'IPython/Extensions/ipy_',
2286+ 'IPython/Extensions/clearcmd',
2287+ 'IPython/Extensions/PhysicalQIn',
2288+ 'IPython/Extensions/scitedirector',
2289+ 'IPython/testing/plugin',
2290+ ]
2291+
2292+#-----------------------------------------------------------------------------
2293+# Functions and classes
2294+#-----------------------------------------------------------------------------
2295+
2296 def main():
2297 """Run the IPython test suite.
2298 """
2299@@ -18,36 +55,39 @@
2300 warnings.filterwarnings('ignore',
2301 'This will be removed soon. Use IPython.testing.util instead')
2302
2303-
2304- # construct list of plugins, omitting the existing doctest plugin
2305- plugins = [IPythonDoctest()]
2306+ argv = sys.argv + [ '--with-ipdoctest',
2307+ '--doctest-tests','--doctest-extension=txt',
2308+ '--detailed-errors',
2309+
2310+ # We add --exe because of setuptools' imbecility (it
2311+ # blindly does chmod +x on ALL files). Nose does the
2312+ # right thing and it tries to avoid executables,
2313+ # setuptools unfortunately forces our hand here. This
2314+ # has been discussed on the distutils list and the
2315+ # setuptools devs refuse to fix this problem!
2316+ '--exe',
2317+ ]
2318+
2319+ # Detect if any tests were required by explicitly calling an IPython
2320+ # submodule or giving a specific path
2321+ has_tests = False
2322+ for arg in sys.argv:
2323+ if 'IPython' in arg or arg.endswith('.py') or \
2324+ (':' in arg and '.py' in arg):
2325+ has_tests = True
2326+ break
2327+ # If nothing was specifically requested, test full IPython
2328+ if not has_tests:
2329+ argv.append('IPython')
2330+
2331+ # Construct list of plugins, omitting the existing doctest plugin.
2332+ plugins = [IPythonDoctest(EXCLUDE)]
2333 for p in nose.plugins.builtin.plugins:
2334 plug = p()
2335 if plug.name == 'doctest':
2336 continue
2337
2338- #print 'adding plugin:',plug.name # dbg
2339+ #print '*** adding plugin:',plug.name # dbg
2340 plugins.append(plug)
2341
2342- argv = sys.argv + ['--doctest-tests','--doctest-extension=txt',
2343- '--detailed-errors',
2344-
2345- # We add --exe because of setuptools' imbecility (it
2346- # blindly does chmod +x on ALL files). Nose does the
2347- # right thing and it tries to avoid executables,
2348- # setuptools unfortunately forces our hand here. This
2349- # has been discussed on the distutils list and the
2350- # setuptools devs refuse to fix this problem!
2351- '--exe',
2352- ]
2353-
2354- has_ip = False
2355- for arg in sys.argv:
2356- if 'IPython' in arg:
2357- has_ip = True
2358- break
2359-
2360- if not has_ip:
2361- argv.append('IPython')
2362-
2363 TestProgram(argv=argv,plugins=plugins)
2364
2365=== modified file 'IPython/testing/plugin/Makefile'
2366--- IPython/testing/plugin/Makefile 2008-09-03 15:54:03 +0000
2367+++ IPython/testing/plugin/Makefile 2008-11-09 05:54:34 +0000
2368@@ -36,8 +36,8 @@
2369 magic: plugin
2370 $(NOSE) IPython.Magic
2371
2372-ipipe: plugin
2373- $(NOSE) IPython.Extensions.ipipe
2374+excolors: plugin
2375+ $(NOSE) IPython.excolors
2376
2377 iplib: plugin
2378 $(NOSE) IPython.iplib
2379
2380=== modified file 'IPython/testing/plugin/ipdoctest.py'
2381--- IPython/testing/plugin/ipdoctest.py 2008-08-24 06:10:55 +0000
2382+++ IPython/testing/plugin/ipdoctest.py 2009-03-11 05:49:08 +0000
2383@@ -65,13 +65,28 @@
2384 # test globals. Once we move over to a clean magic system, this will be done
2385 # with much less ugliness.
2386
2387+class py_file_finder(object):
2388+ def __init__(self,test_filename):
2389+ self.test_filename = test_filename
2390+
2391+ def __call__(self,name):
2392+ from IPython.genutils import get_py_filename
2393+ try:
2394+ get_py_filename(name)
2395+ except IOError:
2396+ test_dir = os.path.dirname(self.test_filename)
2397+ new_path = os.path.join(test_dir,name)
2398+ return get_py_filename(new_path)
2399+
2400+
2401 def _run_ns_sync(self,arg_s,runner=None):
2402 """Modified version of %run that syncs testing namespaces.
2403
2404 This is strictly needed for running doctests that call %run.
2405 """
2406
2407- out = _ip.IP.magic_run_ori(arg_s,runner)
2408+ finder = py_file_finder(_run_ns_sync.test_filename)
2409+ out = _ip.IP.magic_run_ori(arg_s,runner,finder)
2410 _run_ns_sync.test_globs.update(_ip.user_ns)
2411 return out
2412
2413@@ -129,8 +144,7 @@
2414
2415 # Start IPython instance. We customize it to start with minimal frills.
2416 user_ns,global_ns = IPython.ipapi.make_user_namespaces(ipnsdict(),dict())
2417-
2418- IPython.Shell.IPShell(['--classic','--noterm_title'],
2419+ IPython.Shell.IPShell(['--colors=NoColor','--noterm_title'],
2420 user_ns,global_ns)
2421
2422 # Deactivate the various python system hooks added by ipython for
2423@@ -172,13 +186,19 @@
2424 return os.path.splitext(filename)[1].lower() in ('.so','.pyd')
2425
2426
2427-class nodoc(object):
2428+class DocTestSkip(object):
2429+ """Object wrapper for doctests to be skipped."""
2430+
2431+ ds_skip = """Doctest to skip.
2432+ >>> 1 #doctest: +SKIP
2433+ """
2434+
2435 def __init__(self,obj):
2436 self.obj = obj
2437
2438 def __getattribute__(self,key):
2439 if key == '__doc__':
2440- return None
2441+ return DocTestSkip.ds_skip
2442 else:
2443 return getattr(object.__getattribute__(self,'obj'),key)
2444
2445@@ -222,7 +242,7 @@
2446
2447 if hasattr(obj,"skip_doctest"):
2448 #print 'SKIPPING DOCTEST FOR:',obj # dbg
2449- obj = nodoc(obj)
2450+ obj = DocTestSkip(obj)
2451
2452 doctest.DocTestFinder._find(self,tests, obj, name, module,
2453 source_lines, globs, seen)
2454@@ -638,7 +658,8 @@
2455 # when called (rather than unconconditionally updating test.globs here
2456 # for all examples, most of which won't be calling %run anyway).
2457 _run_ns_sync.test_globs = test.globs
2458-
2459+ _run_ns_sync.test_filename = test.filename
2460+
2461 return super(IPDocTestRunner,self).run(test,
2462 compileflags,out,clear_globs)
2463
2464@@ -656,6 +677,22 @@
2465 name = 'extdoctest' # call nosetests with --with-extdoctest
2466 enabled = True
2467
2468+ def __init__(self,exclude_patterns=None):
2469+ """Create a new ExtensionDoctest plugin.
2470+
2471+ Parameters
2472+ ----------
2473+
2474+ exclude_patterns : sequence of strings, optional
2475+ These patterns are compiled as regular expressions, subsequently used
2476+ to exclude any filename which matches them from inclusion in the test
2477+ suite (using pattern.search(), NOT pattern.match() ).
2478+ """
2479+ if exclude_patterns is None:
2480+ exclude_patterns = []
2481+ self.exclude_patterns = map(re.compile,exclude_patterns)
2482+ doctests.Doctest.__init__(self)
2483+
2484 def options(self, parser, env=os.environ):
2485 Plugin.options(self, parser, env)
2486 parser.add_option('--doctest-tests', action='store_true',
2487@@ -688,6 +725,7 @@
2488 self.globs = None
2489 self.extraglobs = None
2490
2491+
2492 def loadTestsFromExtensionModule(self,filename):
2493 bpath,mod = os.path.split(filename)
2494 modname = os.path.splitext(mod)[0]
2495@@ -703,8 +741,8 @@
2496 # a few modifications to control output checking.
2497
2498 def loadTestsFromModule(self, module):
2499- #print 'lTM',module # dbg
2500-
2501+ #print '*** ipdoctest - lTM',module # dbg
2502+
2503 if not self.matches(module.__name__):
2504 log.debug("Doctest doesn't want module %s", module)
2505 return
2506@@ -733,8 +771,6 @@
2507
2508
2509 def loadTestsFromFile(self, filename):
2510- #print 'lTF',filename # dbg
2511-
2512 if is_extension_module(filename):
2513 for t in self.loadTestsFromExtensionModule(filename):
2514 yield t
2515@@ -761,22 +797,10 @@
2516 Modified version that accepts extension modules as valid containers for
2517 doctests.
2518 """
2519- print 'Filename:',filename # dbg
2520-
2521- # XXX - temporarily hardcoded list, will move to driver later
2522- exclude = ['IPython/external/',
2523- 'IPython/platutils_win32',
2524- 'IPython/frontend/cocoa',
2525- 'IPython_doctest_plugin',
2526- 'IPython/Gnuplot',
2527- 'IPython/Extensions/ipy_',
2528- 'IPython/Extensions/PhysicalQIn',
2529- 'IPython/Extensions/scitedirector',
2530- 'IPython/testing/plugin',
2531- ]
2532-
2533- for fex in exclude:
2534- if fex in filename: # substring
2535+ #print '*** ipdoctest- wantFile:',filename # dbg
2536+
2537+ for pat in self.exclude_patterns:
2538+ if pat.search(filename):
2539 #print '###>>> SKIP:',filename # dbg
2540 return False
2541
2542@@ -791,6 +815,23 @@
2543 """
2544 name = 'ipdoctest' # call nosetests with --with-ipdoctest
2545 enabled = True
2546+
2547+ def makeTest(self, obj, parent):
2548+ """Look for doctests in the given object, which will be a
2549+ function, method or class.
2550+ """
2551+ # always use whitespace and ellipsis options
2552+ optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
2553+
2554+ doctests = self.finder.find(obj, module=getmodule(parent))
2555+ if doctests:
2556+ for test in doctests:
2557+ if len(test.examples) == 0:
2558+ continue
2559+
2560+ yield DocTestCase(test, obj=obj,
2561+ optionflags=optionflags,
2562+ checker=self.checker)
2563
2564 def configure(self, options, config):
2565
2566
2567=== added file 'IPython/tests/tclass.py'
2568--- IPython/tests/tclass.py 1970-01-01 00:00:00 +0000
2569+++ IPython/tests/tclass.py 2009-03-13 17:56:19 +0000
2570@@ -0,0 +1,26 @@
2571+"""Simple script to instantiate a class for testing %run"""
2572+
2573+import sys
2574+
2575+# An external test will check that calls to f() work after %run
2576+class foo: pass
2577+
2578+def f():
2579+ return foo()
2580+
2581+# We also want to ensure that while objects remain available for immediate
2582+# access, objects from *previous* runs of the same script get collected, to
2583+# avoid accumulating massive amounts of old references.
2584+class C(object):
2585+ def __init__(self,name):
2586+ self.name = name
2587+
2588+ def __del__(self):
2589+ print 'Deleting object:',self.name
2590+
2591+try:
2592+ name = sys.argv[1]
2593+except IndexError:
2594+ pass
2595+else:
2596+ c = C(name)
2597
2598=== modified file 'IPython/tests/test_magic.py'
2599--- IPython/tests/test_magic.py 2008-09-17 19:01:11 +0000
2600+++ IPython/tests/test_magic.py 2009-03-13 17:56:19 +0000
2601@@ -1,8 +1,21 @@
2602-""" Tests for various magic functions
2603-
2604-Needs to be run by nose (to make ipython session available)
2605-
2606+"""Tests for various magic functions.
2607+
2608+Needs to be run by nose (to make ipython session available).
2609 """
2610+
2611+# Standard library imports
2612+import os
2613+import sys
2614+
2615+# Third-party imports
2616+import nose.tools as nt
2617+
2618+# From our own code
2619+from IPython.testing import decorators as dec
2620+
2621+#-----------------------------------------------------------------------------
2622+# Test functions begin
2623+
2624 def test_rehashx():
2625 # clear up everything
2626 _ip.IP.alias_table.clear()
2627@@ -19,3 +32,96 @@
2628 # rehashx must fill up syscmdlist
2629 scoms = _ip.db['syscmdlist']
2630 assert len(scoms) > 10
2631+
2632+
2633+def doctest_run_ns():
2634+ """Classes declared %run scripts must be instantiable afterwards.
2635+
2636+ In [11]: run tclass
2637+
2638+ In [12]: isinstance(f(),foo)
2639+ Out[12]: True
2640+ """
2641+
2642+
2643+def doctest_run_ns2():
2644+ """Classes declared %run scripts must be instantiable afterwards.
2645+
2646+ In [3]: run tclass.py
2647+
2648+ In [4]: run tclass first_pass
2649+
2650+ In [5]: run tclass second_pass
2651+ Deleting object: first_pass
2652+ """
2653+
2654+
2655+def doctest_hist_f():
2656+ """Test %hist -f with temporary filename.
2657+
2658+ In [9]: import tempfile
2659+
2660+ In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
2661+
2662+ In [11]: %history -n -f $tfile 3
2663+ """
2664+
2665+
2666+def doctest_hist_r():
2667+ """Test %hist -r
2668+
2669+ XXX - This test is not recording the output correctly. Not sure why...
2670+
2671+ In [6]: x=1
2672+
2673+ In [7]: hist -n -r 2
2674+ x=1 # random
2675+ hist -n -r 2 # random
2676+ """
2677+
2678+
2679+def test_shist():
2680+ # Simple tests of ShadowHist class - test generator.
2681+ import os, shutil, tempfile
2682+
2683+ from IPython.Extensions import pickleshare
2684+ from IPython.history import ShadowHist
2685+
2686+ tfile = tempfile.mktemp('','tmp-ipython-')
2687+
2688+ db = pickleshare.PickleShareDB(tfile)
2689+ s = ShadowHist(db)
2690+ s.add('hello')
2691+ s.add('world')
2692+ s.add('hello')
2693+ s.add('hello')
2694+ s.add('karhu')
2695+
2696+ yield nt.assert_equals,s.all(),[(1, 'hello'), (2, 'world'), (3, 'karhu')]
2697+
2698+ yield nt.assert_equal,s.get(2),'world'
2699+
2700+ shutil.rmtree(tfile)
2701+
2702+@dec.skipif_not_numpy
2703+def test_numpy_clear_array_undec():
2704+ _ip.ex('import numpy as np')
2705+ _ip.ex('a = np.empty(2)')
2706+
2707+ yield nt.assert_true,'a' in _ip.user_ns
2708+ _ip.magic('clear array')
2709+ yield nt.assert_false,'a' in _ip.user_ns
2710+
2711+
2712+@dec.skip()
2713+def test_fail_dec(*a,**k):
2714+ yield nt.assert_true, False
2715+
2716+@dec.skip('This one shouldn not run')
2717+def test_fail_dec2(*a,**k):
2718+ yield nt.assert_true, False
2719+
2720+@dec.skipknownfailure
2721+def test_fail_dec3(*a,**k):
2722+ yield nt.assert_true, False
2723+
2724
2725=== modified file 'IPython/twshell.py'
2726--- IPython/twshell.py 2008-04-26 07:17:18 +0000
2727+++ IPython/twshell.py 2009-03-11 06:53:19 +0000
2728@@ -1,3 +1,7 @@
2729+"""Twisted shell support.
2730+
2731+XXX - This module is missing proper docs.
2732+"""
2733 import sys
2734
2735 from twisted.internet import reactor, threads
2736
2737=== modified file 'IPython/ultraTB.py'
2738--- IPython/ultraTB.py 2008-08-24 06:10:55 +0000
2739+++ IPython/ultraTB.py 2009-03-11 06:53:19 +0000
2740@@ -59,8 +59,7 @@
2741 You can implement other color schemes easily, the syntax is fairly
2742 self-explanatory. Please send back new schemes you develop to the author for
2743 possible inclusion in future releases.
2744-
2745-$Id: ultraTB.py 2908 2007-12-30 21:07:46Z vivainio $"""
2746+"""
2747
2748 #*****************************************************************************
2749 # Copyright (C) 2001 Nathaniel Gray <n8gray@caltech.edu>
2750@@ -70,11 +69,6 @@
2751 # the file COPYING, distributed as part of this software.
2752 #*****************************************************************************
2753
2754-from IPython import Release
2755-__author__ = '%s <%s>\n%s <%s>' % (Release.authors['Nathan']+
2756- Release.authors['Fernando'])
2757-__license__ = Release.license
2758-
2759 # Required modules
2760 import inspect
2761 import keyword
2762@@ -98,7 +92,7 @@
2763 # Modified pdb which doesn't damage IPython's readline handling
2764 from IPython import Debugger, PyColorize
2765 from IPython.ipstruct import Struct
2766-from IPython.excolors import ExceptionColors
2767+from IPython.excolors import exception_colors
2768 from IPython.genutils import Term,uniq_stable,error,info
2769
2770 # Globals
2771@@ -320,7 +314,7 @@
2772 self.call_pdb = call_pdb
2773
2774 # Create color table
2775- self.color_scheme_table = ExceptionColors
2776+ self.color_scheme_table = exception_colors()
2777
2778 self.set_colors(color_scheme)
2779 self.old_scheme = color_scheme # save initial value for toggles
2780
2781=== modified file 'IPython/usage.py'
2782--- IPython/usage.py 2008-02-28 18:21:11 +0000
2783+++ IPython/usage.py 2009-03-11 06:53:19 +0000
2784@@ -6,13 +6,6 @@
2785 # the file COPYING, distributed as part of this software.
2786 #*****************************************************************************
2787
2788-# $Id: usage.py 2723 2007-09-07 07:44:16Z fperez $
2789-
2790-from IPython import Release
2791-__author__ = '%s <%s>' % Release.authors['Fernando']
2792-__license__ = Release.license
2793-__version__ = Release.version
2794-
2795 __doc__ = """
2796 IPython -- An enhanced Interactive Python
2797 =========================================
2798@@ -650,5 +643,3 @@
2799 The following magic functions are currently available:
2800
2801 """
2802-
2803-
2804
2805=== modified file 'IPython/wildcard.py'
2806--- IPython/wildcard.py 2008-02-16 09:50:47 +0000
2807+++ IPython/wildcard.py 2009-03-11 06:53:19 +0000
2808@@ -1,7 +1,5 @@
2809 # -*- coding: utf-8 -*-
2810 """Support for wildcard pattern matching in object inspection.
2811-
2812-$Id: OInspect.py 608 2005-07-06 17:52:32Z fperez $
2813 """
2814
2815 #*****************************************************************************
2816
2817=== modified file 'docs/Makefile'
2818--- docs/Makefile 2008-08-28 23:34:53 +0000
2819+++ docs/Makefile 2009-03-11 01:24:53 +0000
2820@@ -5,13 +5,14 @@
2821 SPHINXOPTS =
2822 SPHINXBUILD = sphinx-build
2823 PAPER =
2824+SRCDIR = source
2825
2826 # Internal variables.
2827 PAPEROPT_a4 = -D latex_paper_size=a4
2828 PAPEROPT_letter = -D latex_paper_size=letter
2829-ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
2830+ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
2831
2832-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
2833+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
2834
2835 help:
2836 @echo "Please use \`make <target>' where <target> is one of"
2837@@ -28,7 +29,7 @@
2838 @echo "dist all, and then puts the results in dist/"
2839
2840 clean:
2841- -rm -rf build/* dist/*
2842+ -rm -rf build/* dist/* $(SRCDIR)/api/generated
2843
2844 pdf: latex
2845 cd build/latex && make all-pdf
2846@@ -41,12 +42,16 @@
2847 cp -al build/html dist/
2848 @echo "Build finished. Final docs are in dist/"
2849
2850-html:
2851+html: api
2852 mkdir -p build/html build/doctrees
2853 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
2854 @echo
2855 @echo "Build finished. The HTML pages are in build/html."
2856
2857+api:
2858+ python autogen_api.py
2859+ @echo "Build API docs finished."
2860+
2861 pickle:
2862 mkdir -p build/pickle build/doctrees
2863 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
2864
2865=== added file 'docs/autogen_api.py'
2866--- docs/autogen_api.py 1970-01-01 00:00:00 +0000
2867+++ docs/autogen_api.py 2009-03-11 01:24:53 +0000
2868@@ -0,0 +1,33 @@
2869+#!/usr/bin/env python
2870+"""Script to auto-generate our API docs.
2871+"""
2872+# stdlib imports
2873+import os
2874+import sys
2875+
2876+# local imports
2877+sys.path.append(os.path.abspath('sphinxext'))
2878+from apigen import ApiDocWriter
2879+
2880+#*****************************************************************************
2881+if __name__ == '__main__':
2882+ pjoin = os.path.join
2883+ package = 'IPython'
2884+ outdir = pjoin('source','api','generated')
2885+ docwriter = ApiDocWriter(package,rst_extension='.txt')
2886+ docwriter.package_skip_patterns += [r'\.fixes$',
2887+ r'\.externals$',
2888+ r'\.Extensions',
2889+ r'\.kernel.config',
2890+ r'\.attic',
2891+ ]
2892+ docwriter.module_skip_patterns += [ r'\.FakeModule',
2893+ r'\.cocoa',
2894+ r'\.ipdoctest',
2895+ r'\.Gnuplot',
2896+ ]
2897+ docwriter.write_api_docs(outdir)
2898+ docwriter.write_index(outdir, 'gen',
2899+ relative_to = pjoin('source','api')
2900+ )
2901+ print '%d files written' % len(docwriter.written_modules)
2902
2903=== added directory 'docs/source/api'
2904=== added file 'docs/source/api/index.txt'
2905--- docs/source/api/index.txt 1970-01-01 00:00:00 +0000
2906+++ docs/source/api/index.txt 2009-03-11 01:24:53 +0000
2907@@ -0,0 +1,12 @@
2908+.. _api-index:
2909+
2910+###################
2911+ The IPython API
2912+###################
2913+
2914+.. htmlonly::
2915+
2916+ :Release: |version|
2917+ :Date: |today|
2918+
2919+.. include:: generated/gen.txt
2920
2921=== modified file 'docs/source/conf.py'
2922--- docs/source/conf.py 2008-09-14 07:58:49 +0000
2923+++ docs/source/conf.py 2009-03-11 01:24:53 +0000
2924@@ -36,9 +36,13 @@
2925 # Add any Sphinx extension module names here, as strings. They can be extensions
2926 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
2927 extensions = ['sphinx.ext.autodoc',
2928- 'inheritance_diagram', 'only_directives',
2929+ 'sphinx.ext.doctest',
2930+
2931+ 'only_directives',
2932+ 'inheritance_diagram',
2933 'ipython_console_highlighting',
2934 # 'plot_directive', # disabled for now, needs matplotlib
2935+ 'numpydoc', # to preprocess docstrings
2936 ]
2937
2938 # Add any paths that contain templates here, relative to this directory.
2939
2940=== added file 'docs/source/development/coding_guide.txt'
2941--- docs/source/development/coding_guide.txt 1970-01-01 00:00:00 +0000
2942+++ docs/source/development/coding_guide.txt 2008-10-04 07:47:34 +0000
2943@@ -0,0 +1,141 @@
2944+==============
2945+ Coding guide
2946+==============
2947+
2948+
2949+Coding conventions
2950+==================
2951+
2952+In general, we'll try to follow the standard Python style conventions as
2953+described in Python's `PEP 8`_, the official Python Style Guide.
2954+
2955+.. _PEP 8: http://www.python.org/peps/pep-0008.html
2956+
2957+Other comments:
2958+
2959+- In a large file, top level classes and functions should be separated by 2-3
2960+ lines to make it easier to separate them visually.
2961+
2962+- Use 4 spaces for indentation, *never* use hard tabs.
2963+
2964+- Keep the ordering of methods the same in classes that have the same methods.
2965+ This is particularly true for classes that implement similar interfaces and
2966+ for interfaces that are similar.
2967+
2968+Naming conventions
2969+------------------
2970+
2971+In terms of naming conventions, we'll follow the guidelines of PEP 8. Some of
2972+the existing code doesn't honor this perfectly, but for all new IPython code
2973+(and much existing code is being refactored), we'll use:
2974+
2975+- All ``lowercase`` module names.
2976+
2977+- ``CamelCase`` for class names.
2978+
2979+- ``lowercase_with_underscores`` for methods, functions, variables and
2980+ attributes.
2981+
2982+This may be confusing as some of the existing codebase uses a different
2983+convention (``lowerCamelCase`` for methods and attributes). Slowly, we will
2984+move IPython over to the new convention, providing shadow names for backward
2985+compatibility in public interfaces.
2986+
2987+There are, however, some important exceptions to these rules. In some cases,
2988+IPython code will interface with packages (Twisted, Wx, Qt) that use other
2989+conventions. At some level this makes it impossible to adhere to our own
2990+standards at all times. In particular, when subclassing classes that use other
2991+naming conventions, you must follow their naming conventions. To deal with
2992+cases like this, we propose the following policy:
2993+
2994+- If you are subclassing a class that uses different conventions, use its
2995+ naming conventions throughout your subclass. Thus, if you are creating a
2996+ Twisted Protocol class, used Twisted's
2997+ ``namingSchemeForMethodsAndAttributes.``
2998+
2999+- All IPython's official interfaces should use our conventions. In some cases
3000+ this will mean that you need to provide shadow names (first implement
3001+ ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
3002+ costs, but it will probably be necessary at times. But, please use this
3003+ sparingly!
3004+
3005+Implementation-specific *private* methods will use
3006+``_single_underscore_prefix``. Names with a leading double underscore will
3007+*only* be used in special cases, as they makes subclassing difficult (such
3008+names are not easily seen by child classes).
3009+
3010+Occasionally some run-in lowercase names are used, but mostly for very short
3011+names or where we are implementing methods very similar to existing ones in a
3012+base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
3013+established precedent).
3014+
3015+The old IPython codebase has a big mix of classes and modules prefixed with an
3016+explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
3017+upon, as namespaces offer cleaner prefixing. The only case where this approach
3018+is justified is for classes which are expected to be imported into external
3019+namespaces and a very generic name (like Shell) is too likely to clash with
3020+something else. We'll need to revisit this issue as we clean up and refactor
3021+the code, but in general we should remove as many unnecessary ``IP``/``ip``
3022+prefixes as possible. However, if a prefix seems absolutely necessary the more
3023+specific ``IPY`` or ``ipy`` are preferred.
3024+
3025+
3026+.. _devel-testing:
3027+
3028+Testing system
3029+==============
3030+
3031+It is extremely important that all code contributed to IPython has tests. Tests
3032+should be written as unittests, doctests or as entities that the `Nose`_
3033+testing package will find. Regardless of how the tests are written, we will use
3034+`Nose`_ for discovering and running the tests. `Nose`_ will be required to run
3035+the IPython test suite, but will not be required to simply use IPython.
3036+
3037+.. _Nose: http://code.google.com/p/python-nose/
3038+
3039+Tests of `Twisted`__ using code should be written by subclassing the
3040+``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
3041+done, `Nose`_ will be able to run the tests and the twisted reactor will be
3042+handled correctly.
3043+
3044+.. __: http://www.twistedmatrix.com
3045+
3046+Each subpackage in IPython should have its own ``tests`` directory that
3047+contains all of the tests for that subpackage. This allows each subpackage to
3048+be self-contained. If a subpackage has any dependencies beyond the Python
3049+standard library, the tests for that subpackage should be skipped if the
3050+dependencies are not found. This is very important so users don't get tests
3051+failing simply because they don't have dependencies.
3052+
3053+We also need to look into use Noses ability to tag tests to allow a more
3054+modular approach of running tests.
3055+
3056+.. _devel-config:
3057+
3058+Configuration system
3059+====================
3060+
3061+IPython uses `.ini`_ files for configuration purposes. This represents a huge
3062+improvement over the configuration system used in IPython. IPython works with
3063+these files using the `ConfigObj`_ package, which IPython includes as
3064+``ipython1/external/configobj.py``.
3065+
3066+Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
3067+IPython should contain a ``config`` subdirectory that contains all of the
3068+configuration information for the subpackage. To see how configuration
3069+information is defined (along with defaults) see at the examples in
3070+``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
3071+the configuration information is used, see examples in
3072+``ipython1/kernel/scripts/ipengine.py``.
3073+
3074+Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
3075+are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
3076+validation model. We won't actually use `Traits`_, but will implement
3077+something similar in pure Python. But, even in this new system, we will still
3078+use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
3079+are interested in working on this part of IPython. The current prototype of
3080+``tconfig`` is located in the IPython sandbox.
3081+
3082+.. _.ini: http://docs.python.org/lib/module-ConfigParser.html
3083+.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
3084+.. _Traits: http://code.enthought.com/traits/
3085
3086=== added file 'docs/source/development/doc_guide.txt'
3087--- docs/source/development/doc_guide.txt 1970-01-01 00:00:00 +0000
3088+++ docs/source/development/doc_guide.txt 2009-03-11 06:58:43 +0000
3089@@ -0,0 +1,103 @@
3090+.. _documenting-ipython:
3091+
3092+=====================
3093+ Documenting IPython
3094+=====================
3095+
3096+Standalone documentation
3097+========================
3098+
3099+All standalone documentation should be written in plain text (``.txt``) files
3100+using `reStructuredText`_ for markup and formatting. All such documentation
3101+should be placed in the top level directory ``docs`` of the IPython source
3102+tree. Or, when appropriate, a suitably named subdirectory should be used. The
3103+documentation in this location will serve as the main source for IPython
3104+documentation and all existing documentation should be converted to this
3105+format.
3106+
3107+The actual HTML and PDF docs are built using the Sphinx_ documentation
3108+generation tool. Sphinx has been adopted as the default documentation tool for
3109+Python itself as of version 2.6, as well as by a number of projects that
3110+IPython is related with, such as numpy, scipy, matplotlib, sage and nipy.
3111+
3112+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
3113+.. _Sphinx: http://sphinx.pocoo.org/
3114+
3115+
3116+The rest of this document is mostly taken from the `matploblib
3117+documentation`__; we are using a number of Sphinx tools and extensions written
3118+by the matplotlib team and will mostly follow their conventions, which are
3119+nicely spelled out in their guide. What follows is thus a lightly adapted
3120+version of the matplotlib documentation guide, taken with permission from the
3121+MPL team.
3122+
3123+.. __: http://matplotlib.sourceforge.net/devel/documenting_mpl.html
3124+
3125+
3126+A bit of Python code::
3127+
3128+ for i in range(10):
3129+ print i,
3130+ print "A big number:",2**34
3131+
3132+An interactive Python session::
3133+
3134+ >>> from IPython import genutils
3135+ >>> genutils.get_ipython_dir()
3136+ '/home/fperez/.ipython'
3137+
3138+
3139+An IPython session:
3140+
3141+.. code-block:: ipython
3142+
3143+ In [7]: import IPython
3144+
3145+ In [8]: print "This IPython is version:",IPython.__version__
3146+ This IPython is version: 0.9.1
3147+
3148+ In [9]: 2+4
3149+ Out[9]: 6
3150+
3151+
3152+A bit of shell code:
3153+
3154+.. code-block:: bash
3155+
3156+ cd /tmp
3157+ echo "My home directory is: $HOME"
3158+ ls
3159+
3160+
3161+Docstring format
3162+================
3163+
3164+Good docstrings are very important. Unfortunately, Python itself only provides
3165+a rather loose standard for docstrings (`PEP 257`_), and there is no universally
3166+accepted convention for all the different parts of a complete docstring.
3167+However, the NumPy project has established a very reasonable standard, and has
3168+developed some tools to support the smooth inclusion of such docstrings in
3169+Sphinx-generated manuals. Rather than inventing yet another pseudo-standard,
3170+IPython will be henceforth documented using the NumPy conventions; we carry
3171+copies of some of the NumPy support tools to remain self-contained, but share
3172+back upstream with NumPy any improvements or fixes we may make to the tools.
3173+
3174+The `NumPy documentation guidelines`_ contain detailed information on this
3175+standard, and for a quick overview, the NumPy `example docstring`_ is a useful
3176+read.
3177+
3178+As in the past IPython used epydoc, currently many docstrings still use epydoc
3179+conventions. We will update them as we go, but all new code should be fully
3180+documented using the NumPy standard.
3181+
3182+.. _PEP 257: http://www.python.org/peps/pep-0257.html
3183+.. _NumPy documentation guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
3184+
3185+.. _example docstring: http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt
3186+
3187+Additional PEPs of interest regarding documentation of code. While both of
3188+these were rejected, the ideas therein form much of the basis of docutils (the
3189+machinery to process reStructuredText):
3190+
3191+- `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
3192+- `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
3193
3194=== modified file 'docs/source/development/index.txt'
3195--- docs/source/development/index.txt 2008-09-11 23:58:46 +0000
3196+++ docs/source/development/index.txt 2008-10-04 07:47:34 +0000
3197@@ -1,10 +1,13 @@
3198-==================
3199-Development
3200-==================
3201+===========================
3202+ IPython Developer's Guide
3203+===========================
3204
3205 .. toctree::
3206 :maxdepth: 2
3207
3208- development.txt
3209+ overview.txt
3210+ coding_guide.txt
3211+ doc_guide.txt
3212 roadmap.txt
3213+
3214 notification_blueprint.txt
3215
3216=== renamed file 'docs/source/development/development.txt' => 'docs/source/development/overview.txt'
3217--- docs/source/development/development.txt 2008-09-15 03:37:13 +0000
3218+++ docs/source/development/overview.txt 2008-10-04 07:47:34 +0000
3219@@ -1,32 +1,35 @@
3220+.. This file has a lot of bash but little python, set default role
3221+
3222+.. highlight:: bash
3223+
3224 .. _development:
3225
3226 ==============================
3227-IPython development guidelines
3228+ IPython development overview
3229 ==============================
3230
3231-
3232-Overview
3233-========
3234-
3235-IPython is the next generation of IPython. It is named such for two reasons:
3236-
3237-- Eventually, IPython will become IPython version 1.0.
3238-- This new code base needs to be able to co-exist with the existing IPython until
3239- it is a full replacement for it. Thus we needed a different name. We couldn't
3240- use ``ipython`` (lowercase) as some files systems are case insensitive.
3241-
3242-There are two, no three, main goals of the IPython effort:
3243+Currently, IPython's development tree contains all of the code that used to be
3244+part of IPython since the project's inception in 2001, plus all of the effort
3245+that was known for a while (roughly 2004-2008) as ``IPython1``. The IPyhton1
3246+development was meant to be an effort to:
3247
3248 1. Clean up the existing codebase and write lots of tests.
3249-2. Separate the core functionality of IPython from the terminal to enable IPython
3250- to be used from within a variety of GUI applications.
3251+
3252+2. Separate the core functionality of IPython from the terminal to enable
3253+ IPython to be used from within a variety of GUI applications.
3254+
3255 3. Implement a system for interactive parallel computing.
3256
3257 While the third goal may seem a bit unrelated to the main focus of IPython, it
3258 turns out that the technologies required for this goal are nearly identical
3259 with those required for goal two. This is the main reason the interactive
3260-parallel computing capabilities are being put into IPython proper. Currently
3261-the third of these goals is furthest along.
3262+parallel computing capabilities are being put into IPython proper.
3263+
3264+In the summer of 2008, the IPython1 code was merged back into the mainline, and
3265+now there is a unified codebase. While the above goals aren't completely
3266+implemented for the older code, we do have a proper :ref:`testing system
3267+<devel-testing>` in place (though this is still evolving), unified
3268+documentation and partial implementations of the more separated components.
3269
3270 This document describes IPython from the perspective of developers.
3271
3272@@ -46,16 +49,19 @@
3273
3274 - **Tests**. Each subpackage shoud have its own ``tests`` subdirectory that
3275 contains all of the tests for that package. For information about writing
3276- tests for IPython, see the `Testing System`_ section of this document.
3277+ tests for IPython, see the :ref:`Testing System <devel-testing>` section of
3278+ this document.
3279
3280 - **Configuration**. Each subpackage should have its own ``config``
3281 subdirectory that contains the configuration information for the components
3282 of the subpackage. For information about how the IPython configuration
3283- system works, see the `Configuration System`_ section of this document.
3284+ system works, see the :ref:`Configuration System <devel-config>` section of
3285+ this document.
3286
3287 - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory
3288 that contains all of the command line scripts associated with the subpackage.
3289
3290+
3291 Installation and dependencies
3292 -----------------------------
3293
3294@@ -117,266 +123,132 @@
3295 today 's IPython. Other frontends will likely be more powerful and based
3296 on GUI toolkits.
3297
3298-``notebook``
3299- An application that allows users to work with IPython notebooks.
3300-
3301 ``tools``
3302 This is where general utilities go.
3303
3304
3305-Version control
3306-===============
3307-
3308-In the past, IPython development has been done using `Subversion`__. Recently,
3309-we made the transition to using `Bazaar`__ and `Launchpad`__. This makes it
3310-much easier for people to contribute code to IPython. Here is a sketch of how
3311-to use Bazaar for IPython development. First, you should install Bazaar.
3312-After you have done that, make sure that it is working by getting the latest
3313-main branch of IPython::
3314-
3315- $ bzr branch lp:ipython
3316-
3317-Now you can create a new branch for you to do your work in::
3318-
3319- $ bzr branch ipython ipython-mybranch
3320-
3321-The typical work cycle in this branch will be to make changes in
3322-``ipython-mybranch`` and then commit those changes using the commit command::
3323-
3324- $ ...do work in ipython-mybranch...
3325- $ bzr ci -m "the commit message goes here"
3326+Version control workflow
3327+========================
3328+
3329+All IPython development today is done using the `Bazaar`__ system for
3330+distributed version control and the `Launchpad`__ site for code hosting and bug
3331+tracking. This makes it very easy for anyone to contribute code to IPython.
3332+
3333+.. __: http://bazaar-vcs.org
3334+.. __: http://launchpad.net/ipython
3335+
3336+If you are interested in contributing to IPython, you should familiarize a bit
3337+with how to use bazaar, but this document gives you a concise set of steps to
3338+get started. If you are going to become heavily involved with creating code
3339+for IPython you'll eventually want to have a Launchpad account (free) so you
3340+can publish your own code on the site for review and merging, but small
3341+contributions can be simply sent via email to the IPython list as patches.
3342+
3343+Start by creating what Bazaar calls a `shared repository`_::
3344+
3345+ # You can choose any name you want instead of "ipython-repo"
3346+ bzr init-repo ipython-repo
3347+
3348+.. _shared repository: http://bazaar-vcs.org/SharedRepositoryTutorial
3349+
3350+This creates an empty repository where a lot of related branches can be kept,
3351+and they all reuse common storage. This way, many operations are very fast and
3352+take up less space. Now, go to the newly created repository and make a local
3353+branch of the public trunk::
3354+
3355+ cd ipython-repo
3356+ # This makes a local copy of the public trunk called "trunk-lp"
3357+ bzr branch lp:ipython trunk-lp
3358+
3359+The ``trunk-lp`` branch is meant to always be a pristine copy of the public
3360+trunk. From here, make a personal development copy of the public trunk, where
3361+you'll make your changes::
3362+
3363+ bzr branch trunk-lp trunk-dev
3364+
3365+Now, your working area looks like this::
3366+
3367+ maqroll[ipython-repo]> ls -a
3368+ ./ ../ .bzr/ trunk-dev/ trunk-lp/
3369+
3370+The ``.bzr`` directory is the Bazaar storage area, and you now have both the
3371+reference copy of the public trunk and one working copy for your own
3372+development. You can later make further branches as needed (a common workflow
3373+is to make branches to contain specific feature implementations until they are
3374+ready to be merged).
3375+
3376+The typical work cycle will be to make changes in ``trunk-dev`` and then commit
3377+those changes as often as needed::
3378+
3379+ cd trunk-dev
3380+ # ... implement cool new feature...
3381+ bzr commit -m "Commit message goes here."
3382
3383 Please note that since we now don't use an old-style linear ChangeLog (that
3384 tends to cause problems with distributed version control systems), you should
3385-ensure that your log messages are reasonably detailed. Use a docstring-like
3386-approach in the commit messages (including the second line being left
3387-*blank*)::
3388-
3389- Single line summary of changes being committed.
3390-
3391- - more details when warranted ...
3392- - including crediting outside contributors if they sent the
3393- code/bug/idea!
3394+ensure that your log messages are reasonably detailed. For non-trivial
3395+changes, use a docstring-like approach in the commit messages (including the
3396+second line being left *blank*). Type ``bzr commit`` *without* the ``-m``
3397+switch, and Bazaar will open an editor where you can type a more detailed
3398+message::
3399+
3400+ Single line summary of changes being committed.
3401+
3402+ - more details when warranted ...
3403+ - including crediting outside contributors if they sent the
3404+ code/bug/idea!
3405
3406 If we couple this with a policy of making single commits for each reasonably
3407 atomic change, the bzr log should give an excellent view of the project, and
3408-the `--short` log option becomes a nice summary.
3409-
3410-While working with this branch, it is a good idea to merge in changes that have
3411-been made upstream in the parent branch. This can be done by doing::
3412-
3413- $ bzr pull
3414+the ``--short`` log option becomes a nice summary.
3415+
3416+As you work on the branch, it's a good idea to frequently keep your copy of the
3417+trunk updated with respect to Launchpad. This is done via::
3418+
3419+ cd trunk-lp
3420+ bzr pull
3421+
3422+Bazaar can then merge any changes that were done to the public trunk into your
3423+local branch via::
3424+
3425+ cd trunk-dev
3426+ bzr merge ../trunk-lp
3427+ bzr commit -m"Merged upstream changes"
3428+
3429+This workflow ensures that a local copy stays in sync with the public trunk,
3430+while allowing for local development to be pushed back for public review.
3431+
3432+Once your changes are ready for review, you can push them to Launchpad where
3433+the IPython team can review them and give you feedback. The first time, use::
3434+
3435+ bzr push --remember \
3436+ bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev
3437+
3438+where ``<you>`` is your Launchpad user name. This will make this branch
3439+publicly visible to all. In subsequent uses you can simply run in the branch::
3440+
3441+ bzr push
3442+
3443+.. note::
3444+
3445+ Before you can push your code to Launchpad, you need to configure your SSH
3446+ keys. You can do this by clicking on ``Change details`` for your profile
3447+ and then clicking on the ``SSH Keys`` tab. This should take you to a URL
3448+ of the form ``https://launchpad.net/~<you>/+editsshkeys`` with instructions
3449+ on how to upload your keys.
3450
3451-If this command shows that the branches have diverged, then you should do a
3452-merge instead::
3453-
3454- $ bzr merge lp:ipython
3455-
3456-If you want others to be able to see your branch, you can create an account
3457-with launchpad and push the branch to your own workspace::
3458-
3459- $ bzr push bzr+ssh://<me>@bazaar.launchpad.net/~<me>/+junk/ipython-mybranch
3460-
3461-Finally, once the work in your branch is done, you can merge your changes back
3462-into the `ipython` branch by using merge::
3463-
3464- $ cd ipython
3465- $ merge ../ipython-mybranch
3466- [resolve any conflicts]
3467- $ bzr ci -m "Fixing that bug"
3468- $ bzr push
3469-
3470-But this will require you to have write permissions to the `ipython` branch.
3471-It you don't you can tell one of the IPython devs about your branch and they
3472-can do the merge for you.
3473-
3474-More information about Bazaar workflows can be found `here`__.
3475-
3476-.. __: http://subversion.tigris.org/
3477-.. __: http://bazaar-vcs.org/
3478-.. __: http://www.launchpad.net/ipython
3479-.. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html
3480-
3481-Documentation
3482-=============
3483-
3484-Standalone documentation
3485-------------------------
3486-
3487-All standalone documentation should be written in plain text (``.txt``) files
3488-using `reStructuredText`_ for markup and formatting. All such documentation
3489-should be placed in the top level directory ``docs`` of the IPython source
3490-tree. Or, when appropriate, a suitably named subdirectory should be used. The
3491-documentation in this location will serve as the main source for IPython
3492-documentation and all existing documentation should be converted to this
3493-format.
3494-
3495-In the future, the text files in the ``docs`` directory will be used to
3496-generate all forms of documentation for IPython. This include documentation on
3497-the IPython website as well as *pdf* documentation.
3498-
3499-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
3500-
3501-Docstring format
3502-----------------
3503-
3504-Good docstrings are very important. All new code will use `Epydoc`_ for
3505-generating API docs, so we will follow the `Epydoc`_ conventions. More
3506-specifically, we will use `reStructuredText`_ for markup and formatting, since
3507-it is understood by a wide variety of tools. This means that if in the future
3508-we have any reason to change from `Epydoc`_ to something else, we'll have fewer
3509-transition pains.
3510-
3511-Details about using `reStructuredText`_ for docstrings can be found `here
3512-<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
3513-
3514-.. _Epydoc: http://epydoc.sourceforge.net/
3515-
3516-Additional PEPs of interest regarding documentation of code:
3517-
3518-- `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
3519-- `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
3520-- `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
3521-
3522-
3523-Coding conventions
3524-==================
3525-
3526-General
3527--------
3528-
3529-In general, we'll try to follow the standard Python style conventions as
3530-described here:
3531-
3532-- `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
3533-
3534-
3535-Other comments:
3536-
3537-- In a large file, top level classes and functions should be
3538- separated by 2-3 lines to make it easier to separate them visually.
3539-- Use 4 spaces for indentation.
3540-- Keep the ordering of methods the same in classes that have the same
3541- methods. This is particularly true for classes that implement
3542- similar interfaces and for interfaces that are similar.
3543-
3544-Naming conventions
3545-------------------
3546-
3547-In terms of naming conventions, we'll follow the guidelines from the `Style
3548-Guide for Python Code`_.
3549-
3550-For all new IPython code (and much existing code is being refactored), we'll use:
3551-
3552-- All ``lowercase`` module names.
3553-
3554-- ``CamelCase`` for class names.
3555-
3556-- ``lowercase_with_underscores`` for methods, functions, variables and
3557- attributes.
3558-
3559-This may be confusing as most of the existing IPython codebase uses a different
3560-convention (``lowerCamelCase`` for methods and attributes). Slowly, we will
3561-move IPython over to the new convention, providing shadow names for backward
3562-compatibility in public interfaces.
3563-
3564-There are, however, some important exceptions to these rules. In some cases,
3565-IPython code will interface with packages (Twisted, Wx, Qt) that use other
3566-conventions. At some level this makes it impossible to adhere to our own
3567-standards at all times. In particular, when subclassing classes that use other
3568-naming conventions, you must follow their naming conventions. To deal with
3569-cases like this, we propose the following policy:
3570-
3571-- If you are subclassing a class that uses different conventions, use its
3572- naming conventions throughout your subclass. Thus, if you are creating a
3573- Twisted Protocol class, used Twisted's
3574- ``namingSchemeForMethodsAndAttributes.``
3575-
3576-- All IPython's official interfaces should use our conventions. In some cases
3577- this will mean that you need to provide shadow names (first implement
3578- ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all
3579- costs, but it will probably be necessary at times. But, please use this
3580- sparingly!
3581-
3582-Implementation-specific *private* methods will use
3583-``_single_underscore_prefix``. Names with a leading double underscore will
3584-*only* be used in special cases, as they makes subclassing difficult (such
3585-names are not easily seen by child classes).
3586-
3587-Occasionally some run-in lowercase names are used, but mostly for very short
3588-names or where we are implementing methods very similar to existing ones in a
3589-base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
3590-established precedent).
3591-
3592-The old IPython codebase has a big mix of classes and modules prefixed with an
3593-explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
3594-upon, as namespaces offer cleaner prefixing. The only case where this approach
3595-is justified is for classes which are expected to be imported into external
3596-namespaces and a very generic name (like Shell) is too likely to clash with
3597-something else. We'll need to revisit this issue as we clean up and refactor
3598-the code, but in general we should remove as many unnecessary ``IP``/``ip``
3599-prefixes as possible. However, if a prefix seems absolutely necessary the more
3600-specific ``IPY`` or ``ipy`` are preferred.
3601-
3602-.. _devel_testing:
3603-
3604-Testing system
3605-==============
3606-
3607-It is extremely important that all code contributed to IPython has tests. Tests
3608-should be written as unittests, doctests or as entities that the `Nose`_
3609-testing package will find. Regardless of how the tests are written, we will use
3610-`Nose`_ for discovering and running the tests. `Nose`_ will be required to run
3611-the IPython test suite, but will not be required to simply use IPython.
3612-
3613-.. _Nose: http://code.google.com/p/python-nose/
3614-
3615-Tests of `Twisted`__ using code should be written by subclassing the
3616-``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
3617-done, `Nose`_ will be able to run the tests and the twisted reactor will be
3618-handled correctly.
3619-
3620-.. __: http://www.twistedmatrix.com
3621-
3622-Each subpackage in IPython should have its own ``tests`` directory that
3623-contains all of the tests for that subpackage. This allows each subpackage to
3624-be self-contained. If a subpackage has any dependencies beyond the Python
3625-standard library, the tests for that subpackage should be skipped if the
3626-dependencies are not found. This is very important so users don't get tests
3627-failing simply because they don't have dependencies.
3628-
3629-We also need to look into use Noses ability to tag tests to allow a more
3630-modular approach of running tests.
3631-
3632-.. _devel_config:
3633-
3634-Configuration system
3635-====================
3636-
3637-IPython uses `.ini`_ files for configuration purposes. This represents a huge
3638-improvement over the configuration system used in IPython. IPython works with
3639-these files using the `ConfigObj`_ package, which IPython includes as
3640-``ipython1/external/configobj.py``.
3641-
3642-Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
3643-IPython should contain a ``config`` subdirectory that contains all of the
3644-configuration information for the subpackage. To see how configuration
3645-information is defined (along with defaults) see at the examples in
3646-``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
3647-the configuration information is used, see examples in
3648-``ipython1/kernel/scripts/ipengine.py``.
3649-
3650-Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
3651-are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
3652-validation model. We won't actually use `Traits`_, but will implement
3653-something similar in pure Python. But, even in this new system, we will still
3654-use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
3655-are interested in working on this part of IPython. The current prototype of
3656-``tconfig`` is located in the IPython sandbox.
3657-
3658-.. _.ini: http://docs.python.org/lib/module-ConfigParser.html
3659-.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
3660-.. _Traits: http://code.enthought.com/traits/
3661+Once the branch is publicly visible, using the launchpad interface it can be
3662+marked for merging with the link marked *"Propose for merging into another
3663+branch"*, leaving the default choice of trunk as its target. This way,
3664+Launchpad tracks what changes of this branch are new with respect to the trunk,
3665+others in the team can review it, and merge the changes into the trunk.
3666+
3667+The IPython team has a policy of reviewing all code (both from core members of
3668+the team and from external contributors) before merging it. Code should be
3669+clearly documented (as explained further in this guide), clear and well tested.
3670+We will be happy to provide you with feedback for your code to be a great
3671+contribution to the project, and we've found that peer review of code is an
3672+excellent way to improve the quality of everyone's work.
3673
3674
3675 Installation and testing scenarios
3676@@ -386,43 +258,54 @@
3677 release an IPython version. These scenarios represent different ways of
3678 installing IPython and its dependencies.
3679
3680+
3681 Installation scenarios under Linux and OS X
3682 -------------------------------------------
3683
3684- 1. Install from tarball using ``python setup.py install``.
3685- a. With only readline+nose dependencies installed.
3686- b. With all dependencies installed (readline, zope.interface, Twisted,
3687- foolscap, Sphinx, nose, pyOpenSSL).
3688-
3689- 2. Install using easy_install.
3690-
3691- a. With only readline+nose dependencies installed.
3692- i. Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
3693- ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
3694-
3695- b. With all dependencies already installed.
3696+1. Install from tarball using ``python setup.py install``.
3697+
3698+ * With only readline+nose dependencies installed.
3699+
3700+ * With all dependencies installed (readline, zope.interface, Twisted,
3701+ foolscap, Sphinx, nose, pyOpenSSL).
3702+
3703+2. Install using easy_install.
3704+
3705+ * With only readline+nose dependencies installed.
3706+
3707+ * Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
3708+
3709+ * Optional dependency sets:
3710+ ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
3711+
3712+ * With all dependencies already installed.
3713
3714
3715 Installation scenarios under Win32
3716 ----------------------------------
3717
3718- 1. Install everything from .exe installers
3719- 2. easy_install?
3720+#. Install everything from .exe installers
3721+#. easy_install?
3722
3723
3724 Tests to run for these scenarios
3725 --------------------------------
3726
3727- 1. Run the full test suite.
3728- 2. Start a controller and engines and try a few things by hand.
3729- a. Using ipcluster.
3730- b. Using ipcontroller/ipengine by hand.
3731-
3732- 3. Run a few of the parallel examples.
3733- 4. Try the kernel with and without security with and without PyOpenSSL
3734- installed.
3735- 5. Beat on the IPython terminal a bunch.
3736- 6. Make sure that furl files are being put in proper locations.
3737+#. Run the full test suite.
3738+
3739+#. Start a controller and engines and try a few things by hand.
3740+
3741+ * Using ipcluster.
3742+ * Using ipcontroller/ipengine by hand.
3743+
3744+#. Run a few of the parallel examples.
3745+
3746+#. Try the kernel with and without security with and without PyOpenSSL
3747+ installed.
3748+
3749+#. Beat on the IPython terminal a bunch.
3750+
3751+#. Make sure that furl files are being put in proper locations.
3752
3753
3754 Release checklist
3755
3756=== modified file 'docs/source/index.txt'
3757--- docs/source/index.txt 2008-09-15 03:37:13 +0000
3758+++ docs/source/index.txt 2009-03-11 01:24:53 +0000
3759@@ -17,10 +17,11 @@
3760 interactive/index.txt
3761 parallel/index.txt
3762 config/index.txt
3763+ faq.txt
3764+ history.txt
3765 changes.txt
3766 development/index.txt
3767- faq.txt
3768- history.txt
3769+ api/index.txt
3770 license_and_copyright.txt
3771 credits.txt
3772
3773
3774=== modified file 'docs/source/install/index.txt'
3775--- docs/source/install/index.txt 2008-09-11 23:49:58 +0000
3776+++ docs/source/install/index.txt 2008-10-04 05:37:23 +0000
3777@@ -1,8 +1,8 @@
3778 .. _install_index:
3779
3780-==================
3781+============
3782 Installation
3783-==================
3784+============
3785
3786 .. toctree::
3787 :maxdepth: 2
3788
3789=== modified file 'docs/source/install/install.txt'
3790--- docs/source/install/install.txt 2008-09-13 15:14:14 +0000
3791+++ docs/source/install/install.txt 2008-10-04 07:47:34 +0000
3792@@ -1,77 +1,126 @@
3793+.. There's little Python in this file, so make the default language bash.
3794+
3795+.. highlight:: bash
3796+
3797 Overview
3798 ========
3799
3800-This document describes the steps required to install IPython. IPython is organized into a number of subpackages, each of which has its own dependencies. All of the subpackages come with IPython, so you don't need to download and install them separately. However, to use a given subpackage, you will need to install all of its dependencies.
3801+This document describes the steps required to install IPython. IPython is
3802+organized into a number of subpackages, each of which has its own dependencies.
3803+All of the subpackages come with IPython, so you don't need to download and
3804+install them separately. However, to use a given subpackage, you will need to
3805+install all of its dependencies.
3806
3807
3808 Please let us know if you have problems installing IPython or any of its
3809-dependencies. IPython requires Python version 2.4 or greater. We have not tested
3810-IPython with the upcoming 2.6 or 3.0 versions.
3811+dependencies. IPython requires Python version 2.4 or greater. We have not
3812+tested IPython with the upcoming 2.6 or 3.0 versions, though preliminary
3813+reports of 2.6 usage are encouraging. 3.0 porting will take longer, however.
3814
3815 .. warning::
3816
3817- IPython will not work with Python 2.3 or below.
3818-
3819-Some of the installation approaches use the :mod:`setuptools` package and its :command:`easy_install` command line program. In many scenarios, this provides the most simple method of installing IPython and its dependencies. It is not required though. More information about :mod:`setuptools` can be found on its website.
3820-
3821-More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/.
3822+ IPython will not work with Python 2.3 or below.
3823+
3824+Some of the installation approaches use the :mod:`setuptools` package and its
3825+:command:`easy_install` command line program. In many scenarios, this provides
3826+the most simple method of installing IPython and its dependencies. It is not
3827+required though. More information about :mod:`setuptools` can be found on its
3828+website.
3829+
3830+More general information about installing Python packages can be found in
3831+Python's documentation at http://www.python.org/doc/.
3832+
3833
3834 Installing IPython itself
3835 =========================
3836
3837-Given a properly built Python, the basic interactive IPython shell will work with no external dependencies. However, some Python distributions (particularly on Windows and OS X), don't come with a working :mod:`readline` module. The IPython shell will work without :mod:`readline`, but will lack many features that users depend on, such as tab completion and command line editing. See below for details of how to make sure you have a working :mod:`readline`.
3838+Given a properly built Python, the basic interactive IPython shell will work
3839+with no external dependencies. However, some Python distributions
3840+(particularly on Windows and OS X), don't come with a working :mod:`readline`
3841+module. The IPython shell will work without :mod:`readline`, but will lack
3842+many features that users depend on, such as tab completion and command line
3843+editing. See below for details of how to make sure you have a working
3844+:mod:`readline`.
3845
3846 Installation using easy_install
3847 -------------------------------
3848
3849-If you have :mod:`setuptools` installed, the easiest way of getting IPython is to simple use :command:`easy_install`::
3850-
3851- $ easy_install IPython
3852-
3853-That's it.
3854+If you have :mod:`setuptools` installed, the easiest way of getting IPython is
3855+to use :command:`easy_install`::
3856+
3857+ easy_install IPython
3858+
3859+Unless you've written a custom distutils script as explained `here`__, that will
3860+try to install either in a default system-wide location, which may require
3861+administrator access. If that is the case, you can either run the command with
3862+root privileges::
3863+
3864+ sudo easy_install IPython
3865+
3866+or you can specify an alternate location, for example::
3867+
3868+ easy_install --prefix=~/usr/local IPython
3869+
3870+where this assumes that ``~/usr/local`` is a valid prefix for you to install
3871+packages to in your user account.
3872+
3873+.. __: http://docs.python.org/install/index.html#inst-config-files
3874+
3875
3876 Installation from source
3877 ------------------------
3878
3879-If you don't want to use :command:`easy_install`, or don't have it installed, just grab the latest stable build of IPython from `here <http://ipython.scipy.org/dist/>`_. Then do the following::
3880-
3881- $ tar -xzf ipython.tar.gz
3882- $ cd ipython
3883- $ python setup.py install
3884-
3885-If you are installing to a location (like ``/usr/local``) that requires higher permissions, you may need to run the last command with :command:`sudo`.
3886+If you don't want to use :command:`easy_install`, or don't have it installed,
3887+just grab the latest stable build of IPython from `here
3888+<http://ipython.scipy.org/dist/>`_. Then do the following (using the
3889+appropriate version number)::
3890+
3891+ tar -xzf ipython.tar.gz
3892+ cd ipython
3893+ python setup.py install
3894+
3895+If you are installing to a location (like ``/usr/local``) that requires higher
3896+permissions, you may need to run the last command with :command:`sudo`.
3897
3898 Windows
3899 -------
3900
3901 There are a few caveats for Windows users. The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want. To get an installation with these, there are two choices:
3902
3903-1. Install using :command:`easy_install`.
3904-
3905-2. Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
3906-
3907-3. Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
3908+#. Install using :command:`easy_install`.
3909+
3910+#. Install using our binary ``.exe`` Windows installer, which can be found at
3911+`here <http://ipython.scipy.org/dist/>`_
3912+
3913+#. Install from source, but using :mod:`setuptools` (``python setupegg.py
3914+ install``).
3915
3916 Installing the development version
3917 ----------------------------------
3918
3919-It is also possible to install the development version of IPython from our `Bazaar <http://bazaar-vcs.org/>`_ source code
3920-repository. To do this you will need to have Bazaar installed on your system. Then just do::
3921+It is also possible to install the development version of IPython from our
3922+`Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will
3923+need to have Bazaar installed on your system. Then just do::
3924
3925- $ bzr branch lp:ipython
3926- $ cd ipython
3927- $ python setup.py install
3928+ bzr branch lp:ipython
3929+ cd ipython
3930+ python setup.py install
3931
3932 Again, this last step on Windows won't create ``.bat`` files or Start Menu shortcuts, so you will have to use one of the other approaches listed above.
3933
3934-Some users want to be able to follow the development branch as it changes. If you have :mod:`setuptools` installed, this is easy. Simply replace the last step by::
3935-
3936- $ python setupegg.py develop
3937-
3938-This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your IPython at any time, just do::
3939-
3940- $ bzr pull
3941-
3942+Some users want to be able to follow the development branch as it changes. If
3943+you have :mod:`setuptools` installed, this is easy. Simply replace the last
3944+step by::
3945+
3946+ python setupegg.py develop
3947+
3948+This creates links in the right places and installs the command line script to
3949+the appropriate places. Then, if you want to update your IPython at any time,
3950+just do::
3951+
3952+ bzr pull
3953+
3954+
3955 Basic optional dependencies
3956 ===========================
3957
3958@@ -86,17 +135,24 @@
3959 readline
3960 --------
3961
3962-In principle, all Python distributions should come with a working :mod:`readline` module. But, reality is not quite that simple. There are two common situations where you won't have a working :mod:`readline` module:
3963+In principle, all Python distributions should come with a working
3964+:mod:`readline` module. But, reality is not quite that simple. There are two
3965+common situations where you won't have a working :mod:`readline` module:
3966
3967 * If you are using the built-in Python on Mac OS X.
3968
3969 * If you are running Windows, which doesn't have a :mod:`readline` module.
3970
3971-On OS X, the built-in Python doesn't not have :mod:`readline` because of license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit have been resolved. For many users, libedit may be sufficient.
3972-
3973-Most users on OS X will want to get the full :mod:`readline` module. To get a working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
3974-
3975- $ easy_install readline
3976+On OS X, the built-in Python doesn't not have :mod:`readline` because of
3977+license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has
3978+a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
3979+many of the issues related to the differences between readline and libedit have
3980+been resolved. For many users, libedit may be sufficient.
3981+
3982+Most users on OS X will want to get the full :mod:`readline` module. To get a
3983+working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
3984+
3985+ easy_install readline
3986
3987 .. note:
3988
3989@@ -104,83 +160,112 @@
3990 official python.org binaries) already have readline installed so
3991 you don't have to do this step.
3992
3993-If needed, the readline egg can be build and installed from source (see the wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
3994+If needed, the readline egg can be build and installed from source (see the
3995+wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
3996
3997-On Windows, you will need the PyReadline module. PyReadline is a separate, Windows only implementation of readline that uses native Windows calls through :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes` module, which comes with Python 2.5 and greater, is required by PyReadline. It is available for Python 2.4 at http://python.net/crew/theller/ctypes.
3998+On Windows, you will need the PyReadline module. PyReadline is a separate,
3999+Windows only implementation of readline that uses native Windows calls through
4000+:mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
4001+installer available `here <http://ipython.scipy.org/dist/>`_. The
4002+:mod:`ctypes` module, which comes with Python 2.5 and greater, is required by
4003+PyReadline. It is available for Python 2.4 at
4004+http://python.net/crew/theller/ctypes.
4005
4006 nose
4007 ----
4008
4009-To run the IPython test suite you will need the :mod:`nose` package. Nose provides a great way of sniffing out and running all of the IPython tests. The simplest way of getting nose, is to use :command:`easy_install`::
4010+To run the IPython test suite you will need the :mod:`nose` package. Nose
4011+provides a great way of sniffing out and running all of the IPython tests. The
4012+simplest way of getting nose, is to use :command:`easy_install`::
4013
4014- $ easy_install nose
4015+ easy_install nose
4016
4017 Another way of getting this is to do::
4018
4019- $ easy_install IPython[test]
4020-
4021-For more installation options, see the `nose website <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose installed, you can run IPython's test suite using the iptest command::
4022-
4023- $ iptest
4024+ easy_install IPython[test]
4025+
4026+For more installation options, see the `nose website
4027+<http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose
4028+installed, you can run IPython's test suite using the iptest command::
4029+
4030+ iptest
4031
4032
4033 pexpect
4034 -------
4035
4036-The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's :command:`irunner` script. On Unix platforms (including OS X), just do::
4037+The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
4038+:command:`irunner` script. On Unix platforms (including OS X), just do::
4039
4040- $ easy_install pexpect
4041+ easy_install pexpect
4042
4043 Windows users are out of luck as pexpect does not run there.
4044
4045 Dependencies for IPython.kernel (parallel computing)
4046 ====================================================
4047
4048-The IPython kernel provides a nice architecture for parallel computing. The main focus of this architecture is on interactive parallel computing. These features require a number of additional packages:
4049+The IPython kernel provides a nice architecture for parallel computing. The
4050+main focus of this architecture is on interactive parallel computing. These
4051+features require a number of additional packages:
4052
4053 * zope.interface (yep, we use interfaces)
4054 * Twisted (asynchronous networking framework)
4055 * Foolscap (a nice, secure network protocol)
4056 * pyOpenSSL (security for network connections)
4057
4058-On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
4059+On a Unix style platform (including OS X), if you want to use
4060+:mod:`setuptools`, you can just do::
4061
4062- $ easy_install IPython[kernel] # the first three
4063- $ easy_install IPython[security] # pyOpenSSL
4064+ easy_install IPython[kernel] # the first three
4065+ easy_install IPython[security] # pyOpenSSL
4066
4067 zope.interface and Twisted
4068 --------------------------
4069
4070-On Unix style platforms (including OS X), the simplest way of getting the these is to use :command:`easy_install`::
4071-
4072- $ easy_install zope.interface
4073- $ easy_install Twisted
4074-
4075-Of course, you can also download the source tarballs from the `Twisted website <twistedmatrix.org>`_ and the `zope.interface page at PyPI <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python setup.py install`` if you prefer.
4076-
4077-Windows is a bit different. For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website. This installer includes both zope.interface and Twisted and should just work.
4078+On Unix style platforms (including OS X), the simplest way of getting the these
4079+is to use :command:`easy_install`::
4080+
4081+ easy_install zope.interface
4082+ easy_install Twisted
4083+
4084+Of course, you can also download the source tarballs from the `Twisted website
4085+<twistedmatrix.org>`_ and the `zope.interface page at PyPI
4086+<http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python
4087+setup.py install`` if you prefer.
4088+
4089+Windows is a bit different. For zope.interface and Twisted, simply get the
4090+latest binary ``.exe`` installer from the Twisted website. This installer
4091+includes both zope.interface and Twisted and should just work.
4092
4093 Foolscap
4094 --------
4095
4096-Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
4097+Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to
4098+implement our parallel computing features.
4099
4100 On all platforms a simple::
4101
4102- $ easy_install foolscap
4103+ easy_install foolscap
4104
4105-should work. You can also download the source tarballs from the `Foolscap website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install`` if you prefer.
4106+should work. You can also download the source tarballs from the `Foolscap
4107+website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install``
4108+if you prefer.
4109
4110 pyOpenSSL
4111 ---------
4112
4113-IPython requires an older version of pyOpenSSL (0.6 rather than the current 0.7). There are a couple of options for getting this:
4114-
4115-1. Most Linux distributions have packages for pyOpenSSL.
4116-2. The built-in Python 2.5 on OS X 10.5 already has it installed.
4117-3. There are source tarballs on the pyOpenSSL website. On Unix-like
4118- platforms, these can be built using ``python seutp.py install``.
4119-4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
4120+IPython requires an older version of pyOpenSSL (0.6 rather than the current
4121+0.7). There are a couple of options for getting this:
4122+
4123+1. Most Linux distributions have packages for pyOpenSSL.
4124+
4125+2. The built-in Python 2.5 on OS X 10.5 already has it installed.
4126+
4127+3. There are source tarballs on the pyOpenSSL website. On Unix-like
4128+ platforms, these can be built using ``python seutp.py install``.
4129+
4130+4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website
4131+ <http://pyopenssl.sourceforge.net/>`_.
4132
4133 Dependencies for IPython.frontend (the IPython GUI)
4134 ===================================================
4135@@ -188,4 +273,9 @@
4136 wxPython
4137 --------
4138
4139-Starting with IPython 0.9, IPython has a new IPython.frontend package that has a nice wxPython based IPython GUI. As you would expect, this GUI requires wxPython. Most Linux distributions have wxPython packages available and the built-in Python on OS X comes with wxPython preinstalled. For Windows, a binary installer is available on the `wxPython website <http://www.wxpython.org/>`_.
4140\ No newline at end of file
4141+Starting with IPython 0.9, IPython has a new IPython.frontend package that has
4142+a nice wxPython based IPython GUI. As you would expect, this GUI requires
4143+wxPython. Most Linux distributions have wxPython packages available and the
4144+built-in Python on OS X comes with wxPython preinstalled. For Windows, a
4145+binary installer is available on the `wxPython website
4146+<http://www.wxpython.org/>`_.
4147
4148=== modified file 'docs/source/interactive/reference.txt'
4149--- docs/source/interactive/reference.txt 2008-09-13 22:39:42 +0000
4150+++ docs/source/interactive/reference.txt 2009-03-11 01:24:53 +0000
4151@@ -496,9 +496,9 @@
4152 ip.expose_magic('impall', doimp)
4153
4154 You can also define your own aliased names for magic functions. In your
4155-ipythonrc file, placing a line like:
4156+ipythonrc file, placing a line like::
4157
4158-execute __IP.magic_cl = __IP.magic_clear
4159+ execute __IP.magic_cl = __IP.magic_clear
4160
4161 will define %cl as a new name for %clear.
4162
4163@@ -508,1572 +508,9 @@
4164 information on the '?' system) to get information about any particular
4165 magic function you are interested in.
4166
4167-
4168-Magic commands
4169---------------
4170-
4171-The rest of this section is automatically generated for each release
4172-from the docstrings in the IPython code. Therefore the formatting is
4173-somewhat minimal, but this method has the advantage of having
4174-information always in sync with the code.
4175-
4176-A list of all the magic commands available in IPython's default
4177-installation follows. This is similar to what you'll see by simply
4178-typing %magic at the prompt, but that will also give you information
4179-about magic commands you may have added as part of your personal
4180-customizations.
4181-
4182-.. magic_start
4183-
4184-**%Exit**::
4185-
4186- Exit IPython without confirmation.
4187-
4188-**%Pprint**::
4189-
4190- Toggle pretty printing on/off.
4191-
4192-**%alias**::
4193-
4194- Define an alias for a system command.
4195-
4196- '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
4197-
4198- Then, typing 'alias_name params' will execute the system command 'cmd
4199- params' (from your underlying operating system).
4200-
4201- Aliases have lower precedence than magic functions and Python normal
4202- variables, so if 'foo' is both a Python variable and an alias, the
4203- alias can not be executed until 'del foo' removes the Python variable.
4204-
4205- You can use the %l specifier in an alias definition to represent the
4206- whole line when the alias is called. For example:
4207-
4208- In [2]: alias all echo "Input in brackets: <%l>"\
4209- In [3]: all hello world\
4210- Input in brackets: <hello world>
4211-
4212- You can also define aliases with parameters using %s specifiers (one
4213- per parameter):
4214-
4215- In [1]: alias parts echo first %s second %s\
4216- In [2]: %parts A B\
4217- first A second B\
4218- In [3]: %parts A\
4219- Incorrect number of arguments: 2 expected.\
4220- parts is an alias to: 'echo first %s second %s'
4221-
4222- Note that %l and %s are mutually exclusive. You can only use one or
4223- the other in your aliases.
4224-
4225- Aliases expand Python variables just like system calls using ! or !!
4226- do: all expressions prefixed with '$' get expanded. For details of
4227- the semantic rules, see PEP-215:
4228- http://www.python.org/peps/pep-0215.html. This is the library used by
4229- IPython for variable expansion. If you want to access a true shell
4230- variable, an extra $ is necessary to prevent its expansion by IPython:
4231-
4232- In [6]: alias show echo\
4233- In [7]: PATH='A Python string'\
4234- In [8]: show $PATH\
4235- A Python string\
4236- In [9]: show $$PATH\
4237- /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
4238-
4239- You can use the alias facility to acess all of $PATH. See the %rehash
4240- and %rehashx functions, which automatically create aliases for the
4241- contents of your $PATH.
4242-
4243- If called with no parameters, %alias prints the current alias table.
4244-
4245-**%autocall**::
4246-
4247- Make functions callable without having to type parentheses.
4248-
4249- Usage:
4250-
4251- %autocall [mode]
4252-
4253- The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
4254- value is toggled on and off (remembering the previous state).
4255-
4256- In more detail, these values mean:
4257-
4258- 0 -> fully disabled
4259-
4260- 1 -> active, but do not apply if there are no arguments on the line.
4261-
4262- In this mode, you get:
4263-
4264- In [1]: callable
4265- Out[1]: <built-in function callable>
4266-
4267- In [2]: callable 'hello'
4268- ------> callable('hello')
4269- Out[2]: False
4270-
4271- 2 -> Active always. Even if no arguments are present, the callable
4272- object is called:
4273-
4274- In [4]: callable
4275- ------> callable()
4276-
4277- Note that even with autocall off, you can still use '/' at the start of
4278- a line to treat the first argument on the command line as a function
4279- and add parentheses to it:
4280-
4281- In [8]: /str 43
4282- ------> str(43)
4283- Out[8]: '43'
4284-
4285-**%autoindent**::
4286-
4287- Toggle autoindent on/off (if available).
4288-
4289-**%automagic**::
4290-
4291- Make magic functions callable without having to type the initial %.
4292-
4293- Without argumentsl toggles on/off (when off, you must call it as
4294- %automagic, of course). With arguments it sets the value, and you can
4295- use any of (case insensitive):
4296-
4297- - on,1,True: to activate
4298-
4299- - off,0,False: to deactivate.
4300-
4301- Note that magic functions have lowest priority, so if there's a
4302- variable whose name collides with that of a magic fn, automagic won't
4303- work for that function (you get the variable instead). However, if you
4304- delete the variable (del var), the previously shadowed magic function
4305- becomes visible to automagic again.
4306-
4307-**%bg**::
4308-
4309- Run a job in the background, in a separate thread.
4310-
4311- For example,
4312-
4313- %bg myfunc(x,y,z=1)
4314-
4315- will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
4316- execution starts, a message will be printed indicating the job
4317- number. If your job number is 5, you can use
4318-
4319- myvar = jobs.result(5) or myvar = jobs[5].result
4320-
4321- to assign this result to variable 'myvar'.
4322-
4323- IPython has a job manager, accessible via the 'jobs' object. You can
4324- type jobs? to get more information about it, and use jobs.<TAB> to see
4325- its attributes. All attributes not starting with an underscore are
4326- meant for public use.
4327-
4328- In particular, look at the jobs.new() method, which is used to create
4329- new jobs. This magic %bg function is just a convenience wrapper
4330- around jobs.new(), for expression-based jobs. If you want to create a
4331- new job with an explicit function object and arguments, you must call
4332- jobs.new() directly.
4333-
4334- The jobs.new docstring also describes in detail several important
4335- caveats associated with a thread-based model for background job
4336- execution. Type jobs.new? for details.
4337-
4338- You can check the status of all jobs with jobs.status().
4339-
4340- The jobs variable is set by IPython into the Python builtin namespace.
4341- If you ever declare a variable named 'jobs', you will shadow this
4342- name. You can either delete your global jobs variable to regain
4343- access to the job manager, or make a new name and assign it manually
4344- to the manager (stored in IPython's namespace). For example, to
4345- assign the job manager to the Jobs name, use:
4346-
4347- Jobs = __builtins__.jobs
4348-
4349-**%bookmark**::
4350-
4351- Manage IPython's bookmark system.
4352-
4353- %bookmark <name> - set bookmark to current dir
4354- %bookmark <name> <dir> - set bookmark to <dir>
4355- %bookmark -l - list all bookmarks
4356- %bookmark -d <name> - remove bookmark
4357- %bookmark -r - remove all bookmarks
4358-
4359- You can later on access a bookmarked folder with:
4360- %cd -b <name>
4361- or simply '%cd <name>' if there is no directory called <name> AND
4362- there is such a bookmark defined.
4363-
4364- Your bookmarks persist through IPython sessions, but they are
4365- associated with each profile.
4366-
4367-**%cd**::
4368-
4369- Change the current working directory.
4370-
4371- This command automatically maintains an internal list of directories
4372- you visit during your IPython session, in the variable _dh. The
4373- command %dhist shows this history nicely formatted. You can also
4374- do 'cd -<tab>' to see directory history conveniently.
4375-
4376- Usage:
4377-
4378- cd 'dir': changes to directory 'dir'.
4379-
4380- cd -: changes to the last visited directory.
4381-
4382- cd -<n>: changes to the n-th directory in the directory history.
4383-
4384- cd -b <bookmark_name>: jump to a bookmark set by %bookmark
4385- (note: cd <bookmark_name> is enough if there is no
4386- directory <bookmark_name>, but a bookmark with the name exists.)
4387- 'cd -b <tab>' allows you to tab-complete bookmark names.
4388-
4389- Options:
4390-
4391- -q: quiet. Do not print the working directory after the cd command is
4392- executed. By default IPython's cd command does print this directory,
4393- since the default prompts do not display path information.
4394-
4395- Note that !cd doesn't work for this purpose because the shell where
4396- !command runs is immediately discarded after executing 'command'.
4397-
4398-**%clear**::
4399-
4400- Clear various data (e.g. stored history data)
4401-
4402- %clear out - clear output history
4403- %clear in - clear input history
4404- %clear shadow_compress - Compresses shadow history (to speed up ipython)
4405- %clear shadow_nuke - permanently erase all entries in shadow history
4406- %clear dhist - clear dir history
4407-
4408-**%color_info**::
4409-
4410- Toggle color_info.
4411-
4412- The color_info configuration parameter controls whether colors are
4413- used for displaying object details (by things like %psource, %pfile or
4414- the '?' system). This function toggles this value with each call.
4415-
4416- Note that unless you have a fairly recent pager (less works better
4417- than more) in your system, using colored object information displays
4418- will not work properly. Test it and see.
4419-
4420-**%colors**::
4421-
4422- Switch color scheme for prompts, info system and exception handlers.
4423-
4424- Currently implemented schemes: NoColor, Linux, LightBG.
4425-
4426- Color scheme names are not case-sensitive.
4427-
4428-**%cpaste**::
4429-
4430- Allows you to paste & execute a pre-formatted code block from clipboard
4431-
4432- You must terminate the block with '--' (two minus-signs) alone on the
4433- line. You can also provide your own sentinel with '%paste -s %%' ('%%'
4434- is the new sentinel for this operation)
4435-
4436- The block is dedented prior to execution to enable execution of method
4437- definitions. '>' and '+' characters at the beginning of a line are
4438- ignored, to allow pasting directly from e-mails or diff files. The
4439- executed block is also assigned to variable named 'pasted_block' for
4440- later editing with '%edit pasted_block'.
4441-
4442- You can also pass a variable name as an argument, e.g. '%cpaste foo'.
4443- This assigns the pasted block to variable 'foo' as string, without
4444- dedenting or executing it.
4445-
4446- Do not be alarmed by garbled output on Windows (it's a readline bug).
4447- Just press enter and type -- (and press enter again) and the block
4448- will be what was just pasted.
4449-
4450- IPython statements (magics, shell escapes) are not supported (yet).
4451-
4452-**%debug**::
4453-
4454- Activate the interactive debugger in post-mortem mode.
4455-
4456- If an exception has just occurred, this lets you inspect its stack
4457- frames interactively. Note that this will always work only on the last
4458- traceback that occurred, so you must call this quickly after an
4459- exception that you wish to inspect has fired, because if another one
4460- occurs, it clobbers the previous one.
4461-
4462- If you want IPython to automatically do this on every exception, see
4463- the %pdb magic for more details.
4464-
4465-**%dhist**::
4466-
4467- Print your history of visited directories.
4468-
4469- %dhist -> print full history\
4470- %dhist n -> print last n entries only\
4471- %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
4472-
4473- This history is automatically maintained by the %cd command, and
4474- always available as the global list variable _dh. You can use %cd -<n>
4475- to go to directory number <n>.
4476-
4477- Note that most of time, you should view directory history by entering
4478- cd -<TAB>.
4479-
4480-**%dirs**::
4481-
4482- Return the current directory stack.
4483-
4484-**%doctest_mode**::
4485-
4486- Toggle doctest mode on and off.
4487-
4488- This mode allows you to toggle the prompt behavior between normal
4489- IPython prompts and ones that are as similar to the default IPython
4490- interpreter as possible.
4491-
4492- It also supports the pasting of code snippets that have leading '>>>'
4493- and '...' prompts in them. This means that you can paste doctests from
4494- files or docstrings (even if they have leading whitespace), and the
4495- code will execute correctly. You can then use '%history -tn' to see
4496- the translated history without line numbers; this will give you the
4497- input after removal of all the leading prompts and whitespace, which
4498- can be pasted back into an editor.
4499-
4500- With these features, you can switch into this mode easily whenever you
4501- need to do testing and changes to doctests, without having to leave
4502- your existing IPython session.
4503-
4504-**%ed**::
4505-
4506- Alias to %edit.
4507-
4508-**%edit**::
4509-
4510- Bring up an editor and execute the resulting code.
4511-
4512- Usage:
4513- %edit [options] [args]
4514-
4515- %edit runs IPython's editor hook. The default version of this hook is
4516- set to call the __IPYTHON__.rc.editor command. This is read from your
4517- environment variable $EDITOR. If this isn't found, it will default to
4518- vi under Linux/Unix and to notepad under Windows. See the end of this
4519- docstring for how to change the editor hook.
4520-
4521- You can also set the value of this editor via the command line option
4522- '-editor' or in your ipythonrc file. This is useful if you wish to use
4523- specifically for IPython an editor different from your typical default
4524- (and for Windows users who typically don't set environment variables).
4525-
4526- This command allows you to conveniently edit multi-line code right in
4527- your IPython session.
4528-
4529- If called without arguments, %edit opens up an empty editor with a
4530- temporary file and will execute the contents of this file when you
4531- close it (don't forget to save it!).
4532-
4533-
4534- Options:
4535-
4536- -n <number>: open the editor at a specified line number. By default,
4537- the IPython editor hook uses the unix syntax 'editor +N filename', but
4538- you can configure this by providing your own modified hook if your
4539- favorite editor supports line-number specifications with a different
4540- syntax.
4541-
4542- -p: this will call the editor with the same data as the previous time
4543- it was used, regardless of how long ago (in your current session) it
4544- was.
4545-
4546- -r: use 'raw' input. This option only applies to input taken from the
4547- user's history. By default, the 'processed' history is used, so that
4548- magics are loaded in their transformed version to valid Python. If
4549- this option is given, the raw input as typed as the command line is
4550- used instead. When you exit the editor, it will be executed by
4551- IPython's own processor.
4552-
4553- -x: do not execute the edited code immediately upon exit. This is
4554- mainly useful if you are editing programs which need to be called with
4555- command line arguments, which you can then do using %run.
4556-
4557-
4558- Arguments:
4559-
4560- If arguments are given, the following possibilites exist:
4561-
4562- - The arguments are numbers or pairs of colon-separated numbers (like
4563- 1 4:8 9). These are interpreted as lines of previous input to be
4564- loaded into the editor. The syntax is the same of the %macro command.
4565-
4566- - If the argument doesn't start with a number, it is evaluated as a
4567- variable and its contents loaded into the editor. You can thus edit
4568- any string which contains python code (including the result of
4569- previous edits).
4570-
4571- - If the argument is the name of an object (other than a string),
4572- IPython will try to locate the file where it was defined and open the
4573- editor at the point where it is defined. You can use `%edit function`
4574- to load an editor exactly at the point where 'function' is defined,
4575- edit it and have the file be executed automatically.
4576-
4577- If the object is a macro (see %macro for details), this opens up your
4578- specified editor with a temporary file containing the macro's data.
4579- Upon exit, the macro is reloaded with the contents of the file.
4580-
4581- Note: opening at an exact line is only supported under Unix, and some
4582- editors (like kedit and gedit up to Gnome 2.8) do not understand the
4583- '+NUMBER' parameter necessary for this feature. Good editors like
4584- (X)Emacs, vi, jed, pico and joe all do.
4585-
4586- - If the argument is not found as a variable, IPython will look for a
4587- file with that name (adding .py if necessary) and load it into the
4588- editor. It will execute its contents with execfile() when you exit,
4589- loading any code in the file into your interactive namespace.
4590-
4591- After executing your code, %edit will return as output the code you
4592- typed in the editor (except when it was an existing file). This way
4593- you can reload the code in further invocations of %edit as a variable,
4594- via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
4595- the output.
4596-
4597- Note that %edit is also available through the alias %ed.
4598-
4599- This is an example of creating a simple function inside the editor and
4600- then modifying it. First, start up the editor:
4601-
4602- In [1]: ed\
4603- Editing... done. Executing edited code...\
4604- Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n'
4605-
4606- We can then call the function foo():
4607-
4608- In [2]: foo()\
4609- foo() was defined in an editing session
4610-
4611- Now we edit foo. IPython automatically loads the editor with the
4612- (temporary) file where foo() was previously defined:
4613-
4614- In [3]: ed foo\
4615- Editing... done. Executing edited code...
4616-
4617- And if we call foo() again we get the modified version:
4618-
4619- In [4]: foo()\
4620- foo() has now been changed!
4621-
4622- Here is an example of how to edit a code snippet successive
4623- times. First we call the editor:
4624-
4625- In [8]: ed\
4626- Editing... done. Executing edited code...\
4627- hello\
4628- Out[8]: "print 'hello'\n"
4629-
4630- Now we call it again with the previous output (stored in _):
4631-
4632- In [9]: ed _\
4633- Editing... done. Executing edited code...\
4634- hello world\
4635- Out[9]: "print 'hello world'\n"
4636-
4637- Now we call it with the output #8 (stored in _8, also as Out[8]):
4638-
4639- In [10]: ed _8\
4640- Editing... done. Executing edited code...\
4641- hello again\
4642- Out[10]: "print 'hello again'\n"
4643-
4644-
4645- Changing the default editor hook:
4646-
4647- If you wish to write your own editor hook, you can put it in a
4648- configuration file which you load at startup time. The default hook
4649- is defined in the IPython.hooks module, and you can use that as a
4650- starting example for further modifications. That file also has
4651- general instructions on how to set a new hook for use once you've
4652- defined it.
4653-
4654-**%env**::
4655-
4656- List environment variables.
4657-
4658-**%exit**::
4659-
4660- Exit IPython, confirming if configured to do so.
4661-
4662- You can configure whether IPython asks for confirmation upon exit by
4663- setting the confirm_exit flag in the ipythonrc file.
4664-
4665-**%hist**::
4666-
4667- Alternate name for %history.
4668-
4669-**%history**::
4670-
4671- Print input history (_i<n> variables), with most recent last.
4672-
4673- %history -> print at most 40 inputs (some may be multi-line)\
4674- %history n -> print at most n inputs\
4675- %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
4676-
4677- Each input's number <n> is shown, and is accessible as the
4678- automatically generated variable _i<n>. Multi-line statements are
4679- printed starting at a new line for easy copy/paste.
4680-
4681-
4682- Options:
4683-
4684- -n: do NOT print line numbers. This is useful if you want to get a
4685- printout of many lines which can be directly pasted into a text
4686- editor.
4687-
4688- This feature is only available if numbered prompts are in use.
4689-
4690- -t: (default) print the 'translated' history, as IPython understands it.
4691- IPython filters your input and converts it all into valid Python source
4692- before executing it (things like magics or aliases are turned into
4693- function calls, for example). With this option, you'll see the native
4694- history instead of the user-entered version: '%cd /' will be seen as
4695- '_ip.magic("%cd /")' instead of '%cd /'.
4696-
4697- -r: print the 'raw' history, i.e. the actual commands you typed.
4698-
4699- -g: treat the arg as a pattern to grep for in (full) history.
4700- This includes the "shadow history" (almost all commands ever written).
4701- Use '%hist -g' to show full shadow history (may be very long).
4702- In shadow history, every index nuwber starts with 0.
4703-
4704- -f FILENAME: instead of printing the output to the screen, redirect it to
4705- the given file. The file is always overwritten, though IPython asks for
4706- confirmation first if it already exists.
4707-
4708-**%logoff**::
4709-
4710- Temporarily stop logging.
4711-
4712- You must have previously started logging.
4713-
4714-**%logon**::
4715-
4716- Restart logging.
4717-
4718- This function is for restarting logging which you've temporarily
4719- stopped with %logoff. For starting logging for the first time, you
4720- must use the %logstart function, which allows you to specify an
4721- optional log filename.
4722-
4723-**%logstart**::
4724-
4725- Start logging anywhere in a session.
4726-
4727- %logstart [-o|-r|-t] [log_name [log_mode]]
4728-
4729- If no name is given, it defaults to a file named 'ipython_log.py' in your
4730- current directory, in 'rotate' mode (see below).
4731-
4732- '%logstart name' saves to file 'name' in 'backup' mode. It saves your
4733- history up to that point and then continues logging.
4734-
4735- %logstart takes a second optional parameter: logging mode. This can be one
4736- of (note that the modes are given unquoted):\
4737- append: well, that says it.\
4738- backup: rename (if exists) to name~ and start name.\
4739- global: single logfile in your home dir, appended to.\
4740- over : overwrite existing log.\
4741- rotate: create rotating logs name.1~, name.2~, etc.
4742-
4743- Options:
4744-
4745- -o: log also IPython's output. In this mode, all commands which
4746- generate an Out[NN] prompt are recorded to the logfile, right after
4747- their corresponding input line. The output lines are always
4748- prepended with a '#[Out]# ' marker, so that the log remains valid
4749- Python code.
4750-
4751- Since this marker is always the same, filtering only the output from
4752- a log is very easy, using for example a simple awk call:
4753-
4754- awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
4755-
4756- -r: log 'raw' input. Normally, IPython's logs contain the processed
4757- input, so that user lines are logged in their final form, converted
4758- into valid Python. For example, %Exit is logged as
4759- '_ip.magic("Exit"). If the -r flag is given, all input is logged
4760- exactly as typed, with no transformations applied.
4761-
4762- -t: put timestamps before each input line logged (these are put in
4763- comments).
4764-
4765-**%logstate**::
4766-
4767- Print the status of the logging system.
4768-
4769-**%logstop**::
4770-
4771- Fully stop logging and close log file.
4772-
4773- In order to start logging again, a new %logstart call needs to be made,
4774- possibly (though not necessarily) with a new filename, mode and other
4775- options.
4776-
4777-**%lsmagic**::
4778-
4779- List currently available magic functions.
4780-
4781-**%macro**::
4782-
4783- Define a set of input lines as a macro for future re-execution.
4784-
4785- Usage:\
4786- %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
4787-
4788- Options:
4789-
4790- -r: use 'raw' input. By default, the 'processed' history is used,
4791- so that magics are loaded in their transformed version to valid
4792- Python. If this option is given, the raw input as typed as the
4793- command line is used instead.
4794-
4795- This will define a global variable called `name` which is a string
4796- made of joining the slices and lines you specify (n1,n2,... numbers
4797- above) from your input history into a single string. This variable
4798- acts like an automatic function which re-executes those lines as if
4799- you had typed them. You just type 'name' at the prompt and the code
4800- executes.
4801-
4802- The notation for indicating number ranges is: n1-n2 means 'use line
4803- numbers n1,...n2' (the endpoint is included). That is, '5-7' means
4804- using the lines numbered 5,6 and 7.
4805-
4806- Note: as a 'hidden' feature, you can also use traditional python slice
4807- notation, where N:M means numbers N through M-1.
4808-
4809- For example, if your history contains (%hist prints it):
4810-
4811- 44: x=1\
4812- 45: y=3\
4813- 46: z=x+y\
4814- 47: print x\
4815- 48: a=5\
4816- 49: print 'x',x,'y',y\
4817-
4818- you can create a macro with lines 44 through 47 (included) and line 49
4819- called my_macro with:
4820-
4821- In [51]: %macro my_macro 44-47 49
4822-
4823- Now, typing `my_macro` (without quotes) will re-execute all this code
4824- in one pass.
4825-
4826- You don't need to give the line-numbers in order, and any given line
4827- number can appear multiple times. You can assemble macros with any
4828- lines from your input history in any order.
4829-
4830- The macro is a simple object which holds its value in an attribute,
4831- but IPython's display system checks for macros and executes them as
4832- code instead of printing them when you type their name.
4833-
4834- You can view a macro's contents by explicitly printing it with:
4835-
4836- 'print macro_name'.
4837-
4838- For one-off cases which DON'T contain magic function calls in them you
4839- can obtain similar results by explicitly executing slices from your
4840- input history with:
4841-
4842- In [60]: exec In[44:48]+In[49]
4843-
4844-**%magic**::
4845-
4846- Print information about the magic function system.
4847-
4848-**%mglob**::
4849-
4850- This program allows specifying filenames with "mglob" mechanism.
4851- Supported syntax in globs (wilcard matching patterns)::
4852-
4853- *.cpp ?ellowo*
4854- - obvious. Differs from normal glob in that dirs are not included.
4855- Unix users might want to write this as: "*.cpp" "?ellowo*"
4856- rec:/usr/share=*.txt,*.doc
4857- - get all *.txt and *.doc under /usr/share,
4858- recursively
4859- rec:/usr/share
4860- - All files under /usr/share, recursively
4861- rec:*.py
4862- - All .py files under current working dir, recursively
4863- foo
4864- - File or dir foo
4865- !*.bak readme*
4866- - readme*, exclude files ending with .bak
4867- !.svn/ !.hg/ !*_Data/ rec:.
4868- - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
4869- Trailing / is the key, \ does not work!
4870- dir:foo
4871- - the directory foo if it exists (not files in foo)
4872- dir:*
4873- - all directories in current folder
4874- foo.py bar.* !h* rec:*.py
4875- - Obvious. !h* exclusion only applies for rec:*.py.
4876- foo.py is *not* included twice.
4877- @filelist.txt
4878- - All files listed in 'filelist.txt' file, on separate lines.
4879-
4880-**%page**::
4881-
4882- Pretty print the object and display it through a pager.
4883-
4884- %page [options] OBJECT
4885-
4886- If no object is given, use _ (last output).
4887-
4888- Options:
4889-
4890- -r: page str(object), don't pretty-print it.
4891-
4892-**%pdb**::
4893-
4894- Control the automatic calling of the pdb interactive debugger.
4895-
4896- Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
4897- argument it works as a toggle.
4898-
4899- When an exception is triggered, IPython can optionally call the
4900- interactive pdb debugger after the traceback printout. %pdb toggles
4901- this feature on and off.
4902-
4903- The initial state of this feature is set in your ipythonrc
4904- configuration file (the variable is called 'pdb').
4905-
4906- If you want to just activate the debugger AFTER an exception has fired,
4907- without having to type '%pdb on' and rerunning your code, you can use
4908- the %debug magic.
4909-
4910-**%pdef**::
4911-
4912- Print the definition header for any callable object.
4913-
4914- If the object is a class, print the constructor information.
4915-
4916-**%pdoc**::
4917-
4918- Print the docstring for an object.
4919-
4920- If the given object is a class, it will print both the class and the
4921- constructor docstrings.
4922-
4923-**%pfile**::
4924-
4925- Print (or run through pager) the file where an object is defined.
4926-
4927- The file opens at the line where the object definition begins. IPython
4928- will honor the environment variable PAGER if set, and otherwise will
4929- do its best to print the file in a convenient form.
4930-
4931- If the given argument is not an object currently defined, IPython will
4932- try to interpret it as a filename (automatically adding a .py extension
4933- if needed). You can thus use %pfile as a syntax highlighting code
4934- viewer.
4935-
4936-**%pinfo**::
4937-
4938- Provide detailed information about an object.
4939-
4940- '%pinfo object' is just a synonym for object? or ?object.
4941-
4942-**%popd**::
4943-
4944- Change to directory popped off the top of the stack.
4945-
4946-**%profile**::
4947-
4948- Print your currently active IPyhton profile.
4949-
4950-**%prun**::
4951-
4952- Run a statement through the python code profiler.
4953-
4954- Usage:\
4955- %prun [options] statement
4956-
4957- The given statement (which doesn't require quote marks) is run via the
4958- python profiler in a manner similar to the profile.run() function.
4959- Namespaces are internally managed to work correctly; profile.run
4960- cannot be used in IPython because it makes certain assumptions about
4961- namespaces which do not hold under IPython.
4962-
4963- Options:
4964-
4965- -l <limit>: you can place restrictions on what or how much of the
4966- profile gets printed. The limit value can be:
4967-
4968- * A string: only information for function names containing this string
4969- is printed.
4970-
4971- * An integer: only these many lines are printed.
4972-
4973- * A float (between 0 and 1): this fraction of the report is printed
4974- (for example, use a limit of 0.4 to see the topmost 40% only).
4975-
4976- You can combine several limits with repeated use of the option. For
4977- example, '-l __init__ -l 5' will print only the topmost 5 lines of
4978- information about class constructors.
4979-
4980- -r: return the pstats.Stats object generated by the profiling. This
4981- object has all the information about the profile in it, and you can
4982- later use it for further analysis or in other functions.
4983-
4984- -s <key>: sort profile by given key. You can provide more than one key
4985- by using the option several times: '-s key1 -s key2 -s key3...'. The
4986- default sorting key is 'time'.
4987-
4988- The following is copied verbatim from the profile documentation
4989- referenced below:
4990-
4991- When more than one key is provided, additional keys are used as
4992- secondary criteria when the there is equality in all keys selected
4993- before them.
4994-
4995- Abbreviations can be used for any key names, as long as the
4996- abbreviation is unambiguous. The following are the keys currently
4997- defined:
4998-
4999- Valid Arg Meaning\
5000- "calls" call count\
The diff has been truncated for viewing.

Subscribers

People subscribed via source and target branches