diff --git a/docs/source/about/credits.txt b/docs/source/about/credits.txt index e639448..1f4c945 100644 --- a/docs/source/about/credits.txt +++ b/docs/source/about/credits.txt @@ -4,205 +4,206 @@ Credits ======= -IPython is led by Fernando Pérez. +IPython was started and continues to be led by Fernando Pérez. -As of this writing, the following developers have joined the core team: +Core developers +=============== -* [Robert Kern] : co-mentored the 2005 - Google Summer of Code project to develop python interactive - notebooks (XML documents) and graphical interface. This project - was awarded to the students Tzanko Matev and - Toni Alatalo . +As of this writing, core development team consists of the following +developers: -* [Brian Granger] : extending IPython to allow - support for interactive parallel computing. +* **Fernando Pérez** Project creator and leader, + IPython core, parallel computing infrastructure, testing, release manager. -* [Benjamin (Min) Ragan-Kelley]: key work on IPython's parallel - computing infrastructure. +* **Robert Kern** Co-mentored the 2005 Google Summer of + Code project, work on IPython's core. -* [Ville Vainio] : Ville has made many improvements - to the core of IPython and was the maintainer of the main IPython - trunk from version 0.7.1 to 0.8.4. +* **Brian Granger** Parallel computing + infrastructure, IPython core. -* [Gael Varoquaux] : work on the merged - architecture for the interpreter as of version 0.9, implementing a new WX GUI - based on this system. +* **Benjamin (Min) Ragan-Kelley** Parallel computing + infrastructure. -* [Barry Wark] : implementing a new Cocoa GUI, as well - as work on the new interpreter architecture and Twisted support. +* **Ville Vainio** IPython core, maintainer of IPython + trunk from version 0.7.2 to 0.8.4. -* [Laurent Dufrechou] : development of the WX - GUI support. +* **Gael Varoquaux** wxPython IPython GUI, + frontend architecture. -* [Jörgen Stenarson] : maintainer of the - PyReadline project, necessary for IPython under windows. +* **Barry Wark** Cocoa GUI, frontend architecture. +* **Laurent Dufrechou** wxPython IPython GUI. + +* **Jörgen Stenarson** Maintainer of the + PyReadline project, which is needed for IPython under windows. + +Special thanks +============== The IPython project is also very grateful to: -Bill Bumgarner : for providing the DPyGetOpt module -which gives very powerful and convenient handling of command-line -options (light years ahead of what Python 2.1.1's getopt module does). +Bill Bumgarner , for providing the DPyGetOpt module that +IPython used for parsing command line options through version 0.10. -Ka-Ping Yee : for providing the Itpl module for -convenient and powerful string interpolation with a much nicer syntax -than formatting through the '%' operator. +Ka-Ping Yee , for providing the Itpl module for convenient +and powerful string interpolation with a much nicer syntax than formatting +through the '%' operator. -Arnd Baecker : for his many very useful -suggestions and comments, and lots of help with testing and -documentation checking. Many of IPython's newer features are a result of -discussions with him (bugs are still my fault, not his). +Arnd Baecker , for his many very useful +suggestions and comments, and lots of help with testing and documentation +checking. Many of IPython's newer features are a result of discussions with +him. -Obviously Guido van Rossum and the whole Python development team, that -goes without saying. +Obviously Guido van Rossum and the whole Python development team, for creating +a great language for interactive computing. -IPython's website is generously hosted at http://ipython.scipy.orgby -Enthought (http://www.enthought.com). I am very grateful to them and all -of the SciPy team for their contribution. +Enthought (http://www.enthought.com), for hosting IPython's website and +supporting the project in various ways over the years. Fernando would also like to thank Stephen Figgins , -an O'Reilly Python editor. His Oct/11/2001 article about IPP and -LazyPython, was what got this project started. You can read it at: +an O'Reilly Python editor. His October 11, 2001 article about IPP and +LazyPython, was what got this project started. You can read it at http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html. -And last but not least, all the kind IPython users who have emailed new code, -bug reports, fixes, comments and ideas. A brief list follows, please let us -know if we have ommitted your name by accident: +Contributors +============ + +And last but not least, all the kind IPython contributors who have contributed +new code, bug reports, fixes, comments and ideas. A brief list follows, please +let us know if we have omitted your name by accident: -* Dan Milstein . A bold refactoring of the - core prefilter stuff in the IPython interpreter. +* Dan Milstein A bold refactor of the core prefilter + machinery in the IPython interpreter. -* [Jack Moffit] Bug fixes, including the infamous - color problem. This bug alone caused many lost hours and - frustration, many thanks to him for the fix. I've always been a - fan of Ogg & friends, now I have one more reason to like these folks. - Jack is also contributing with Debian packaging and many other - things. +* Jack Moffit Bug fixes, including the infamous color + problem. This bug alone caused many lost hours and frustration, many thanks + to him for the fix. I've always been a fan of Ogg & friends, now I have one + more reason to like these folks. Jack is also contributing with Debian + packaging and many other things. -* [Alexander Schmolck] Emacs work, bug - reports, bug fixes, ideas, lots more. The ipython.el mode for - (X)Emacs is Alex's code, providing full support for IPython under - (X)Emacs. +* Alexander Schmolck Emacs work, bug reports, bug + fixes, ideas, lots more. The ipython.el mode for (X)Emacs is Alex's code, + providing full support for IPython under (X)Emacs. -* [Andrea Riciputi] Mac OSX - information, Fink package management. +* Andrea Riciputi Mac OSX information, Fink + package management. -* [Gary Bishop] Bug reports, and patches to work - around the exception handling idiosyncracies of WxPython. Readline - and color support for Windows. +* Gary Bishop Bug reports, and patches to work around the + exception handling idiosyncracies of WxPython. Readline and color support + for Windows. -* [Jeffrey Collins] Bug reports. Much - improved readline support, including fixes for Python 2.3. +* Jeffrey Collins . Bug reports. Much improved + readline support, including fixes for Python 2.3. -* [Dryice Liu] FreeBSD port. +* Dryice Liu FreeBSD port. -* [Mike Heeter] +* Mike Heeter -* [Christopher Hart] PDB integration. +* Christopher Hart PDB integration. -* [Milan Zamazal] Emacs info. +* Milan Zamazal Emacs info. -* [Philip Hisley] +* Philip Hisley -* [Holger Krekel] Tab completion, lots - more. +* Holger Krekel Tab completion, lots more. -* [Robin Siebler] +* Robin Siebler -* [Ralf Ahlbrink] +* Ralf Ahlbrink -* [Thorsten Kampe] +* Thorsten Kampe -* [Fredrik Kant] Windows setup. +* Fredrik Kant Windows setup. -* [Syver Enstad] Windows setup. +* Syver Enstad Windows setup. -* [Richard] Global embedding. +* Richard Global embedding. -* [Hayden Callow] Gnuplot.py 1.6 +* Hayden Callow Gnuplot.py 1.6 compatibility. -* [Leonardo Santagada] Fixes for Windows +* Leonardo Santagada Fixes for Windows installation. -* [Christopher Armstrong] Bugfixes. +* Christopher Armstrong Bugfixes. -* [Francois Pinard] Code and +* Francois Pinard Code and documentation fixes. -* [Cory Dodt] Bug reports and Windows +* Cory Dodt Bug reports and Windows ideas. Patches for Windows installer. -* [Olivier Aubert] New magics. +* Olivier Aubert New magics. -* [King C. Shu] Autoindent patch. +* King C. Shu Autoindent patch. -* [Chris Drexler] Readline packages for +* Chris Drexler Readline packages for Win32/CygWin. -* [Gustavo Cordova Avila] EvalDict code for +* Gustavo Cordova Avila EvalDict code for nice, lightweight string interpolation. -* [Kasper Souren] Bug reports, ideas. +* Kasper Souren Bug reports, ideas. -* [Gever Tulley] Code contributions. +* Gever Tulley Code contributions. -* [Ralf Schmitt] Bug reports & fixes. +* Ralf Schmitt Bug reports & fixes. -* [Oliver Sander] Bug reports. +* Oliver Sander Bug reports. -* [Rod Holland] Bug reports and fixes to +* Rod Holland Bug reports and fixes to logging module. -* [Daniel 'Dang' Griffith] +* Daniel 'Dang' Griffith Fixes, enhancement suggestions for system shell use. -* [Viktor Ransmayr] Tests and +* Viktor Ransmayr Tests and reports on Windows installation issues. Contributed a true Windows binary installer. -* [Mike Salib] Help fixing a subtle bug related +* Mike Salib Help fixing a subtle bug related to traceback printing. -* [W.J. van der Laan] Bash-like +* W.J. van der Laan Bash-like prompt specials. -* [Antoon Pardon] Critical fix for +* Antoon Pardon Critical fix for the multithreaded IPython. -* [John Hunter] Matplotlib +* John Hunter Matplotlib author, helped with all the development of support for matplotlib in IPyhton, including making necessary changes to matplotlib itself. -* [Matthew Arnison] Bug reports, '%run -d' idea. +* Matthew Arnison Bug reports, '%run -d' idea. -* [Prabhu Ramachandran] Help +* Prabhu Ramachandran Help with (X)Emacs support, threading patches, ideas... -* [Norbert Tretkowski] help with Debian +* Norbert Tretkowski help with Debian packaging and distribution. -* [George Sakkis] New matcher for +* George Sakkis New matcher for tab-completing named arguments of user-defined functions. -* [Jörgen Stenarson] Wildcard +* Jörgen Stenarson Wildcard support implementation for searching namespaces. -* [Vivian De Smedt] Debugger enhancements, +* Vivian De Smedt Debugger enhancements, so that when pdb is activated from within IPython, coloring, tab completion and other features continue to work seamlessly. -* [Scott Tsai] Support for automatic +* Scott Tsai Support for automatic editor invocation on syntax errors (see http://www.scipy.net/roundup/ipython/issue36). -* [Alexander Belchenko] Improvements for win32 +* Alexander Belchenko Improvements for win32 paging system. -* [Will Maier] Official OpenBSD port. +* Will Maier Official OpenBSD port. -* [Ondrej Certik] : set up the IPython docs to use the new +* Ondrej Certik Set up the IPython docs to use the new Sphinx system used by Python, Matplotlib and many more projects. -* [Stefan van der Walt] : support for the new config system. +* Stefan van der Walt Design and prototype of the + Traits based config system. diff --git a/docs/source/about/history.txt b/docs/source/about/history.txt index 439f8e4..d0a34cd 100644 --- a/docs/source/about/history.txt +++ b/docs/source/about/history.txt @@ -7,21 +7,22 @@ History Origins ======= -IPython was starting in 2001 by Fernando Perez. IPython as we know it -today grew out of the following three projects: - -* ipython by Fernando Pérez. I was working on adding - Mathematica-type prompts and a flexible configuration system - (something better than $PYTHONSTARTUP) to the standard Python - interactive interpreter. +IPython was starting in 2001 by Fernando Perez while he was a graduate student +at the University of Colorado, Boulder. IPython as we know it today grew out +of the following three projects: + +* ipython by Fernando Pérez. Fernando began using Python and ipython began as + an outgrowth of his desire for things like Mathematica-style prompts, access + to previous output (again like Mathematica's % syntax) and a flexible + configuration system (something better than :envvar:`PYTHONSTARTUP`). * IPP by Janko Hauser. Very well organized, great usability. Had - an old help system. IPP was used as the 'container' code into - which I added the functionality from ipython and LazyPython. + an old help system. IPP was used as the "container" code into + which Fernando added the functionality from ipython and LazyPython. * LazyPython by Nathan Gray. Simple but very powerful. The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks were all taken from here. -Here is how Fernando describes it: +Here is how Fernando describes the early history of IPython: When I found out about IPP and LazyPython I tried to join all three into a unified system. I thought this could provide a very nice @@ -31,8 +32,3 @@ Here is how Fernando describes it: think it worked reasonably well, though it was a lot more work than I had initially planned. -Today and how we got here -========================= - -This needs to be filled in. - diff --git a/docs/source/about/license_and_copyright.txt b/docs/source/about/license_and_copyright.txt index fb7d0df..e88da84 100644 --- a/docs/source/about/license_and_copyright.txt +++ b/docs/source/about/license_and_copyright.txt @@ -7,7 +7,8 @@ License and Copyright License ======= -IPython is licensed under the terms of the new or revised BSD license, as follows:: +IPython is licensed under the terms of the new or revised BSD license, as +follows:: Copyright (c) 2008, IPython Development Team @@ -44,25 +45,24 @@ About the IPython Development Team ================================== Fernando Perez began IPython in 2001 based on code from Janko Hauser - and Nathaniel Gray . Fernando is still + and Nathaniel Gray . Fernando is still the project lead. The IPython Development Team is the set of all contributors to the IPython project. This includes all of the IPython subprojects. Here is a list of the currently active contributors: - * Matthieu Brucher - * Ondrej Certik - * Laurent Dufrechou - * Robert Kern - * Brian E. Granger - * Fernando Perez (project leader) - * Benjamin Ragan-Kelley - * Ville M. Vainio - * Gael Varoququx - * Stefan van der Walt - * Tech-X Corporation - * Barry Wark +* Matthieu Brucher +* Ondrej Certik +* Laurent Dufrechou +* Robert Kern +* Brian E. Granger +* Fernando Perez (project leader) +* Benjamin Ragan-Kelley +* Ville M. Vainio +* Gael Varoququx +* Stefan van der Walt +* Barry Wark If your name is missing, please add it. @@ -71,13 +71,16 @@ Our Copyright Policy IPython uses a shared copyright model. Each contributor maintains copyright over their contributions to IPython. But, it is important to note that these -contributions are typically only changes to the repositories. Thus, the -IPython source code, in its entirety is not the copyright of any single person -or institution. Instead, it is the collective copyright of the entire IPython -Development Team. If individual contributors want to maintain a record of what -changes/contributions they have specific copyright on, they should indicate -their copyright in the commit message of the change, when they commit the -change to one of the IPython repositories. +contributions are typically only changes (diffs/commits) to the repositories. +Thus, the IPython source code, in its entirety is not the copyright of any +single person or institution. Instead, it is the collective copyright of the +entire IPython Development Team. If individual contributors want to maintain a +record of what changes/contributions they have specific copyright on, they +should indicate their copyright in the commit message of the change, when they +commit the change to one of the IPython repositories. + +Any new code contributed to IPython must be licensed under the BSD license or +a similar (MIT) open source license. Miscellaneous ============= diff --git a/docs/source/config/extension.txt b/docs/source/config/extension.txt new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/source/config/extension.txt diff --git a/docs/source/config/new_config.txt b/docs/source/config/new_config.txt deleted file mode 100644 index 3f25b35..0000000 --- a/docs/source/config/new_config.txt +++ /dev/null @@ -1,28 +0,0 @@ -======================== -New configuration system -======================== - -IPython has a configuration system. When running IPython for the first time, -reasonable defaults are used for the configuration. The configuration of IPython -can be changed in two ways: - - * Configuration files - * Commands line options (which override the configuration files) - -IPython has a separate configuration file for each subpackage. Thus, the main -configuration files are (in your ``~/.ipython`` directory): - - * ``ipython1.core.ini`` - * ``ipython1.kernel.ini`` - * ``ipython1.notebook.ini`` - -To create these files for the first time, do the following:: - - from IPython.kernel.config import config_manager as kernel_config - kernel_config.write_default_config_file() - -But, you should only need to do this if you need to modify the defaults. If needed -repeat this process with the ``notebook`` and ``core`` configuration as well. If you -are running into problems with IPython, you might try deleting these configuration -files. - diff --git a/docs/source/development/coding_guide.txt b/docs/source/development/coding_guide.txt index 4d1de1f..ec7ff28 100644 --- a/docs/source/development/coding_guide.txt +++ b/docs/source/development/coding_guide.txt @@ -79,64 +79,78 @@ the code, but in general we should remove as many unnecessary ``IP``/``ip`` prefixes as possible. However, if a prefix seems absolutely necessary the more specific ``IPY`` or ``ipy`` are preferred. +Older material +============== -.. _devel-testing: +General +------- -Testing system -============== +In general, we'll try to follow the standard Python style conventions as +described here: + +* `Style Guide for Python Code `_ + + +Other comments: + +* In a large file, top level classes and functions should be + separated by 2-3 lines to make it easier to separate them visually. +* Use 4 spaces for indentation. +* Keep the ordering of methods the same in classes that have the same + methods. This is particularly true for classes that implement an interface. + +Naming conventions +------------------ + +In terms of naming conventions, we'll follow the guidelines from the `Style +Guide for Python Code`_. + +For all new IPython code (and much existing code is being refactored), we'll +use: + +* All ``lowercase`` module names. + +* ``CamelCase`` for class names. + +* ``lowercase_with_underscores`` for methods, functions, variables and + attributes. + +There are, however, some important exceptions to these rules. In some cases, +IPython code will interface with packages (Twisted, Wx, Qt) that use other +conventions. At some level this makes it impossible to adhere to our own +standards at all times. In particular, when subclassing classes that use other +naming conventions, you must follow their naming conventions. To deal with +cases like this, we propose the following policy: + +* If you are subclassing a class that uses different conventions, use its + naming conventions throughout your subclass. Thus, if you are creating a + Twisted Protocol class, used Twisted's + ``namingSchemeForMethodsAndAttributes.`` + +* All IPython's official interfaces should use our conventions. In some cases + this will mean that you need to provide shadow names (first implement + ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all + costs, but it will probably be necessary at times. But, please use this + sparingly! + +Implementation-specific *private* methods will use +``_single_underscore_prefix``. Names with a leading double underscore will +*only* be used in special cases, as they makes subclassing difficult (such +names are not easily seen by child classes). + +Occasionally some run-in lowercase names are used, but mostly for very short +names or where we are implementing methods very similar to existing ones in a +base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had +established precedent). + +The old IPython codebase has a big mix of classes and modules prefixed with an +explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned +upon, as namespaces offer cleaner prefixing. The only case where this approach +is justified is for classes which are expected to be imported into external +namespaces and a very generic name (like Shell) is too likely to clash with +something else. We'll need to revisit this issue as we clean up and refactor +the code, but in general we should remove as many unnecessary ``IP``/``ip`` +prefixes as possible. However, if a prefix seems absolutely necessary the more +specific ``IPY`` or ``ipy`` are preferred. -It is extremely important that all code contributed to IPython has tests. Tests -should be written as unittests, doctests or as entities that the `Nose`_ -testing package will find. Regardless of how the tests are written, we will use -`Nose`_ for discovering and running the tests. `Nose`_ will be required to run -the IPython test suite, but will not be required to simply use IPython. - -.. _Nose: http://code.google.com/p/python-nose/ - -Tests of `Twisted`__ using code should be written by subclassing the -``TestCase`` class that comes with ``twisted.trial.unittest``. When this is -done, `Nose`_ will be able to run the tests and the twisted reactor will be -handled correctly. - -.. __: http://www.twistedmatrix.com - -Each subpackage in IPython should have its own ``tests`` directory that -contains all of the tests for that subpackage. This allows each subpackage to -be self-contained. If a subpackage has any dependencies beyond the Python -standard library, the tests for that subpackage should be skipped if the -dependencies are not found. This is very important so users don't get tests -failing simply because they don't have dependencies. - -We also need to look into use Noses ability to tag tests to allow a more -modular approach of running tests. - -.. _devel-config: - -Configuration system -==================== - -IPython uses `.ini`_ files for configuration purposes. This represents a huge -improvement over the configuration system used in IPython. IPython works with -these files using the `ConfigObj`_ package, which IPython includes as -``ipython1/external/configobj.py``. - -Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of -IPython should contain a ``config`` subdirectory that contains all of the -configuration information for the subpackage. To see how configuration -information is defined (along with defaults) see at the examples in -``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how -the configuration information is used, see examples in -``ipython1/kernel/scripts/ipengine.py``. - -Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We -are calling this new layer, ``tconfig``, as it will use a `Traits`_-like -validation model. We won't actually use `Traits`_, but will implement -something similar in pure Python. But, even in this new system, we will still -use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you -are interested in working on this part of IPython. The current prototype of -``tconfig`` is located in the IPython sandbox. - -.. _.ini: http://docs.python.org/lib/module-ConfigParser.html -.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html -.. _Traits: http://code.enthought.com/traits/ diff --git a/docs/source/development/config_blueprint.txt b/docs/source/development/config_blueprint.txt deleted file mode 100644 index fdfd31b..0000000 --- a/docs/source/development/config_blueprint.txt +++ /dev/null @@ -1,34 +0,0 @@ -========================================= -Notes on the IPython configuration system -========================================= - -This document has some random notes on the configuration system. - -To start, an IPython process needs: - -* Configuration files -* Command line options -* Additional files (FURL files, extra scripts, etc.) - -It feeds these things into the core logic of the process, and as output, -produces: - -* Log files -* Security files - -There are a number of things that complicate this: - -* A process may need to be started on a different host that doesn't have - any of the config files or additional files. Those files need to be - moved over and put in a staging area. The process then needs to be told - about them. -* The location of the output files should somehow be set by config files or - command line options. -* Our config files are very hierarchical, but command line options are flat, - making it difficult to relate command line options to config files. -* Some processes (like ipcluster and the daemons) have to manage the input and - output files for multiple different subprocesses, each possibly on a - different host. Ahhhh! -* Our configurations are not singletons. A given user will likely have - many different configurations for different clusters. - diff --git a/docs/source/development/contributing.txt b/docs/source/development/contributing.txt new file mode 100644 index 0000000..6a11f72 --- /dev/null +++ b/docs/source/development/contributing.txt @@ -0,0 +1,191 @@ +How to contribute to IPython +============================ + +IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_. +This makes it easy for people to contribute to the development of IPython. +There are several ways in which you can join in. + +If you have a small change that you want to send to the team, you can edit your +bazaar checkout of IPython (see below) in-place, and ask bazaar for the +differences:: + + $ cd /path/to/your/copy/of/ipython + $ bzr diff > my_fixes.diff + +This produces a patch file with your fixes, which we can apply to the source +tree. This file should then be attached to a ticket in our `bug tracker +`_, indicating what it does. + +This model of creating small, self-contained patches works very well and there +are open source projects that do their entire development this way. However, +in IPython we have found that for tracking larger changes, making use of +bazaar's full capabilities in conjunction with Launchpad's code hosting +services makes for a much better experience. + +Making your own branch of IPython allows you to refine your changes over time, +track the development of the main team, and propose your own full version of +the code for others to use and review, with a minimum amount of fuss. The next +parts of this document will explain how to do this. + +Install Bazaar and create a Launchpad account +--------------------------------------------- + +First make sure you have installed Bazaar (see their `website +`_). To see that Bazaar is installed and knows about +you, try the following:: + + $ bzr whoami + Joe Coder + +This should display your name and email. Next, you will want to create an +account on the `Launchpad website `_ and setup your +ssh keys. For more information of setting up your ssh keys, see `this link +`_. + +Get the main IPython branch from Launchpad +------------------------------------------ + +Now, you can get a copy of the main IPython development branch (we call this +the "trunk"):: + + $ bzr branch lp:ipython + +Create a working branch +----------------------- + +When working on IPython, you won't actually make edits directly to the +:file:`lp:ipython` branch. Instead, you will create a separate branch for your +changes. For now, let's assume you want to do your work in a branch named +"ipython-mybranch". Create this branch by doing:: + + $ bzr branch ipython ipython-mybranch + +When you actually create a branch, you will want to give it a name that +reflects the nature of the work that you will be doing in it, like +"install-docs-update". + +Make edits in your working branch +--------------------------------- + +Now you are ready to actually make edits in your :file:`ipython-mybranch` +branch. Before doing this, it is helpful to install this branch so you can +test your changes as you work. This is easiest if you have setuptools +installed. Then, just do:: + + $ cd ipython-mybranch + $ python setupegg.py develop + +Now, make some changes. After a while, you will want to commit your changes. +This let's Bazaar know that you like the changes you have made and gives you +an opportunity to keep a nice record of what you have done. This looks like +this:: + + $ ...do work in ipython-mybranch... + $ bzr commit -m "the commit message goes here" + +Please note that since we now don't use an old-style linear ChangeLog (that +tends to cause problems with distributed version control systems), you should +ensure that your log messages are reasonably detailed. Use a docstring-like +approach in the commit messages (including the second line being left +*blank*):: + + Single line summary of changes being committed. + + * more details when warranted ... + * including crediting outside contributors if they sent the + code/bug/idea! + +As you work, you will repeat this edit/commit cycle many times. If you work on +your branch for a long time, you will also want to get the latest changes from +the :file:`lp:ipython` branch. This can be done with the following sequence of +commands:: + + $ ls + ipython + ipython-mybranch + + $ cd ipython + $ bzr pull + $ cd ../ipython-mybranch + $ bzr merge ../ipython + $ bzr commit -m "Merging changes from trunk" + +Along the way, you should also run the IPython test suite. You can do this +using the :command:`iptest` command (which is basically a customized version of +:command:`nosetests`):: + + $ cd + $ iptest + +The :command:`iptest` command will also pick up and run any tests you have +written. See :ref:`testing documentation ` for further details +on the testing system. + + +Post your branch and request a code review +------------------------------------------ + +Once you are done with your edits, you should post your branch on Launchpad so +that other IPython developers can review the changes and help you merge your +changes into the main development branch. To post your branch on Launchpad, +do:: + + $ cd ipython-mybranch + $ bzr push lp:~yourusername/ipython/ipython-mybranch + +Then, go to the `IPython Launchpad site `_, and you +should see your branch under the "Code" tab. If you click on your branch, you +can provide a short description of the branch as well as mark its status. Most +importantly, you should click the link that reads "Propose for merging into +another branch". What does this do? + +This let's the other IPython developers know that your branch is ready to be +reviewed and merged into the main development branch. During this review +process, other developers will give you feedback and help you get your code +ready to be merged. What types of things will we be looking for: + +* All code is documented. +* All code has tests. +* The entire IPython test suite passes. + +Once your changes have been reviewed and approved, someone will merge them +into the main development branch. + + +Some notes for core developers when merging third-party contributions +===================================================================== + +Core developers, who ultimately merge any approved branch (from themselves, +another developer, or any third-party contribution) will typically use +:command:`bzr merge` to merge the branch into the trunk and push it to the +main Launcphad site. This is a short list of things to keep in mind when doing +this process, so that the project history is easy to understand in the long +run, and that generating release notes is as painless and accurate as +possible. + +- When you merge any non-trivial functionality (from one small bug fix to a + big feature branch), please remember to always edit the :file:`changes.txt` + file accordingly. This file has one main section for each release, and if + you edit it as you go, noting what new features, bug fixes or API changes + you have made, the release notes will be almost finished when they are + needed later. This is much easier if done when you merge the work, rather + than weeks or months later by re-reading a massive Bazaar log. + +- When big merges are done, the practice of putting a summary commit message + in the merge is *extremely* useful. It makes this kind of job much nicer, + because that summary log message can be almost copy/pasted without changes, + if it was well written, rather than dissecting the next-level messages from + the individual commits. + +- It's important that we remember to always credit who gave us something if + it's not the committer. In general, we have been fairly good on this front, + this is just a reminder to keep things up. As a note, if you are ever + committing something that is completely (or almost so) a third-party + contribution, do the commit as:: + + $ bzr commit --author="Someone Else" + + This way it will show that name separately in the log, which makes it even + easier to spot. Obviously we often rework third party contributions + extensively, but this is still good to keep in mind for cases when we don't + touch the code too much. \ No newline at end of file diff --git a/docs/source/development/doc_guide.txt b/docs/source/development/doc_guide.txt index 00ae59f..f23d826 100644 --- a/docs/source/development/doc_guide.txt +++ b/docs/source/development/doc_guide.txt @@ -102,3 +102,40 @@ machinery to process reStructuredText): - `Docstring Processing System Framework `_ - `Docutils Design Specification `_ +Older material +============== + +Documentation +============= + +Standalone documentation +------------------------ + +All standalone documentation should be written in plain text (``.txt``) files +using reStructuredText [reStructuredText]_ for markup and formatting. All such +documentation should be placed in directory :file:`docs/source` of the IPython +source tree. The documentation in this location will serve as the main source +for IPython documentation and all existing documentation should be converted +to this format. + +To build the final documentation, we use Sphinx [Sphinx]_. Once you have +Sphinx installed, you can build the html docs yourself by doing:: + + $ cd ipython-mybranch/docs + $ make html + +Docstring format +---------------- + +Good docstrings are very important. All new code should have docstrings that +are formatted using reStructuredText for markup and formatting, since it is +understood by a wide variety of tools. Details about using reStructuredText +for docstrings can be found `here +`_. + +Additional PEPs of interest regarding documentation of code: + +* `Docstring Conventions `_ +* `Docstring Processing System Framework `_ +* `Docutils Design Specification `_ + diff --git a/docs/source/development/index.txt b/docs/source/development/index.txt index ae031d9..010cf96 100644 --- a/docs/source/development/index.txt +++ b/docs/source/development/index.txt @@ -1,16 +1,25 @@ -=========================== - IPython Developer's Guide -=========================== +.. _developer_guide: + +========================= +IPython developer's guide +========================= .. toctree:: :maxdepth: 2 - overview.txt + contributing.txt coding_guide.txt doc_guide.txt + testing.txt + release.txt roadmap.txt notification_blueprint.txt - config_blueprint.txt reorg.txt + +.. [Bazaar] Bazaar. http://bazaar-vcs.org/ +.. [Launchpad] Launchpad. http://www.launchpad.net/ipython +.. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html +.. [Sphinx] Sphinx. http://sphinx.pocoo.org/ +.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/ \ No newline at end of file diff --git a/docs/source/development/notification_blueprint.txt b/docs/source/development/notification_blueprint.txt index b665368..c874de9 100644 --- a/docs/source/development/notification_blueprint.txt +++ b/docs/source/development/notification_blueprint.txt @@ -39,29 +39,38 @@ The notification center must: What's not included =================== -As written, the :mod:`IPython.kernel.core.notificaiton` module does not: +As written, the :mod:`IPython.kernel.core.notification` module does not: * Provide out-of-process or network notifications (these should be handled by a separate, Twisted aware module in :mod:`IPython.kernel`). -* Provide zope.interface-style interfaces for the notification system (these +* Provide zope.interface style interfaces for the notification system (these should also be provided by the :mod:`IPython.kernel` module). Use Cases ========= -The following use cases describe the main intended uses of the notificaiton module and illustrate the main success scenario for each use case: +The following use cases describe the main intended uses of the notification +module and illustrate the main success scenario for each use case: - 1. Dwight Schroot is writing a frontend for the IPython project. His frontend is stuck in the stone age and must communicate synchronously with an IPython.kernel.core.Interpreter instance. Because code is executed in blocks by the Interpreter, Dwight's UI freezes every time he executes a long block of code. To keep track of the progress of his long running block, Dwight adds the following code to his frontend's set-up code:: +Scenario 1 +---------- - from IPython.kernel.core.notification import NotificationCenter - center = NotificationCenter.sharedNotificationCenter - center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification) - - and elsewhere in his front end:: +Dwight Schroot is writing a frontend for the IPython project. His frontend is +stuck in the stone age and must communicate synchronously with an +:mod:`IPython.kernel.core.Interpreter` instance. Because code is executed in blocks +by the Interpreter, Dwight's UI freezes every time he executes a long block of +code. To keep track of the progress of his long running block, Dwight adds the +following code to his frontend's set-up code:: + + from IPython.kernel.core.notification import NotificationCenter + center = NotificationCenter.sharedNotificationCenter + center.registerObserver(self, type=IPython.kernel.core.Interpreter.STDOUT_NOTIFICATION_TYPE, notifying_object=self.interpreter, callback=self.stdout_notification) - def stdout_notification(self, type, notifying_object, out_string=None): - self.writeStdOut(out_string) +and elsewhere in his front end:: + + def stdout_notification(self, type, notifying_object, out_string=None): + self.writeStdOut(out_string) If everything works, the Interpreter will (according to its published API) fire a notification via the @@ -78,7 +87,10 @@ Like magic, Dwight's frontend is able to provide output, even during long-running calculations. Now if Jim could just convince Dwight to use Twisted... -2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is +Scenario 2 +---------- + +Boss Hog is writing a frontend for the IPython project. Because Boss Hog is stuck in the stone age, his frontend will be written in a new Fortran-like dialect of python and will run only from the command line. Because he doesn't need any fancy notification system and is used to worrying about every cycle @@ -92,17 +104,20 @@ Interpreter (or any other object) fires an event for which there are no registered observers. Of course, the same notificaiton-enabled Interpreter can then be used in frontends that require notifications, thus saving the IPython project from a nasty civil war. - -3. Barry is wrting a frontend for the IPython project. Because Barry's front -end is the *new hotness*, it uses an asynchronous event model to communicate -with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the -IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the + +Scenario 3 +---------- + +Barry is wrting a frontend for the IPython project. Because Barry's front end +is the *new hotness*, it uses an asynchronous event model to communicate with +a Twisted :mod:`IPython.kernel.engineservice` that communicates with the +IPython :class:`IPython.kernel.core.interpreter.Interpreter`. Using the :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the :mod:`IPython.kernel.core.notification` module, Barry's frontend can register for notifications from the interpreter that are delivered asynchronously. Even if Barry's frontend is running on a separate process or even host from the Interpreter, the notifications are delivered, as if by dark and twisted magic. -Just like Dwight's frontend, Barry's frontend can now recieve notifications of +Just like Dwight's frontend, Barry's frontend can now receive notifications of e.g. writing to stdout/stderr, opening/closing an external file, an exception in the executing code, etc. diff --git a/docs/source/development/overview.txt b/docs/source/development/overview.txt index 30cfcc7..12a6f48 100644 --- a/docs/source/development/overview.txt +++ b/docs/source/development/overview.txt @@ -1,518 +1,8 @@ -.. _development: -============================== -IPython development guidelines -============================== -Overview -======== -This document describes IPython from the perspective of developers. Most -importantly, it gives information for people who want to contribute to the -development of IPython. So if you want to help out, read on! -How to contribute to IPython -============================ -IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_. -This makes it easy for people to contribute to the development of IPython. -There are several ways in which you can join in. -If you have a small change that you want to send to the team, you can edit your -bazaar checkout of IPython (see below) in-place, and ask bazaar for the -differences:: - - $ cd /path/to/your/copy/of/ipython - $ bzr diff > my_fixes.diff - -This produces a patch file with your fixes, which we can apply to the source -tree. This file should then be attached to a ticket in our `bug tracker -`_, indicating what it does. - -This model of creating small, self-contained patches works very well and there -are open source projects that do their entire development this way. However, -in IPython we have found that for tracking larger changes, making use of -bazaar's full capabilities in conjunction with Launchpad's code hosting -services makes for a much better experience. - -Making your own branch of IPython allows you to refine your changes over time, -track the development of the main team, and propose your own full version of -the code for others to use and review, with a minimum amount of fuss. The next -parts of this document will explain how to do this. - -Install Bazaar and create a Launchpad account ---------------------------------------------- - -First make sure you have installed Bazaar (see their `website -`_). To see that Bazaar is installed and knows about -you, try the following:: - - $ bzr whoami - Joe Coder - -This should display your name and email. Next, you will want to create an -account on the `Launchpad website `_ and setup your -ssh keys. For more information of setting up your ssh keys, see `this link -`_. - -Get the main IPython branch from Launchpad ------------------------------------------- - -Now, you can get a copy of the main IPython development branch (we call this -the "trunk"):: - - $ bzr branch lp:ipython - -Create a working branch ------------------------ - -When working on IPython, you won't actually make edits directly to the -:file:`lp:ipython` branch. Instead, you will create a separate branch for your -changes. For now, let's assume you want to do your work in a branch named -"ipython-mybranch". Create this branch by doing:: - - $ bzr branch ipython ipython-mybranch - -When you actually create a branch, you will want to give it a name that -reflects the nature of the work that you will be doing in it, like -"install-docs-update". - -Make edits in your working branch ---------------------------------- - -Now you are ready to actually make edits in your :file:`ipython-mybranch` -branch. Before doing this, it is helpful to install this branch so you can -test your changes as you work. This is easiest if you have setuptools -installed. Then, just do:: - - $ cd ipython-mybranch - $ python setupegg.py develop - -Now, make some changes. After a while, you will want to commit your changes. -This let's Bazaar know that you like the changes you have made and gives you -an opportunity to keep a nice record of what you have done. This looks like -this:: - - $ ...do work in ipython-mybranch... - $ bzr commit -m "the commit message goes here" - -Please note that since we now don't use an old-style linear ChangeLog (that -tends to cause problems with distributed version control systems), you should -ensure that your log messages are reasonably detailed. Use a docstring-like -approach in the commit messages (including the second line being left -*blank*):: - - Single line summary of changes being committed. - - * more details when warranted ... - * including crediting outside contributors if they sent the - code/bug/idea! - -As you work, you will repeat this edit/commit cycle many times. If you work on -your branch for a long time, you will also want to get the latest changes from -the :file:`lp:ipython` branch. This can be done with the following sequence of -commands:: - - $ ls - ipython - ipython-mybranch - - $ cd ipython - $ bzr pull - $ cd ../ipython-mybranch - $ bzr merge ../ipython - $ bzr commit -m "Merging changes from trunk" - -Along the way, you should also run the IPython test suite. You can do this -using the :command:`iptest` command (which is basically a customized version of -:command:`nosetests`):: - - $ cd - $ iptest - -The :command:`iptest` command will also pick up and run any tests you have -written. See :ref:`testing documentation ` for further details -on the testing system. - - -Post your branch and request a code review ------------------------------------------- - -Once you are done with your edits, you should post your branch on Launchpad so -that other IPython developers can review the changes and help you merge your -changes into the main development branch. To post your branch on Launchpad, -do:: - - $ cd ipython-mybranch - $ bzr push lp:~yourusername/ipython/ipython-mybranch - -Then, go to the `IPython Launchpad site `_, and you -should see your branch under the "Code" tab. If you click on your branch, you -can provide a short description of the branch as well as mark its status. Most -importantly, you should click the link that reads "Propose for merging into -another branch". What does this do? - -This let's the other IPython developers know that your branch is ready to be -reviewed and merged into the main development branch. During this review -process, other developers will give you feedback and help you get your code -ready to be merged. What types of things will we be looking for: - -* All code is documented. -* All code has tests. -* The entire IPython test suite passes. - -Once your changes have been reviewed and approved, someone will merge them -into the main development branch. - - -Some notes for core developers when merging third-party contributions -===================================================================== - -Core developers, who ultimately merge any approved branch (from themselves, -another developer, or any third-party contribution) will typically use -:command:`bzr merge` to merge the branch into the trunk and push it to the -main Launcphad site. This is a short list of things to keep in mind when doing -this process, so that the project history is easy to understand in the long -run, and that generating release notes is as painless and accurate as -possible. - -- When you merge any non-trivial functionality (from one small bug fix to a - big feature branch), please remember to always edit the :file:`changes.txt` - file accordingly. This file has one main section for each release, and if - you edit it as you go, noting what new features, bug fixes or API changes - you have made, the release notes will be almost finished when they are - needed later. This is much easier if done when you merge the work, rather - than weeks or months later by re-reading a massive Bazaar log. - -- When big merges are done, the practice of putting a summary commit message - in the merge is *extremely* useful. It makes this kind of job much nicer, - because that summary log message can be almost copy/pasted without changes, - if it was well written, rather than dissecting the next-level messages from - the individual commits. - -- It's important that we remember to always credit who gave us something if - it's not the committer. In general, we have been fairly good on this front, - this is just a reminder to keep things up. As a note, if you are ever - committing something that is completely (or almost so) a third-party - contribution, do the commit as:: - - $ bzr commit --author="Someone Else" - - This way it will show that name separately in the log, which makes it even - easier to spot. Obviously we often rework third party contributions - extensively, but this is still good to keep in mind for cases when we don't - touch the code too much. - - -Documentation -============= - -Standalone documentation ------------------------- - -All standalone documentation should be written in plain text (``.txt``) files -using reStructuredText [reStructuredText]_ for markup and formatting. All such -documentation should be placed in directory :file:`docs/source` of the IPython -source tree. The documentation in this location will serve as the main source -for IPython documentation and all existing documentation should be converted -to this format. - -To build the final documentation, we use Sphinx [Sphinx]_. Once you have -Sphinx installed, you can build the html docs yourself by doing:: - - $ cd ipython-mybranch/docs - $ make html - -Docstring format ----------------- - -Good docstrings are very important. All new code should have docstrings that -are formatted using reStructuredText for markup and formatting, since it is -understood by a wide variety of tools. Details about using reStructuredText -for docstrings can be found `here -`_. - -Additional PEPs of interest regarding documentation of code: - -* `Docstring Conventions `_ -* `Docstring Processing System Framework `_ -* `Docutils Design Specification `_ - - -Coding conventions -================== - -General -------- - -In general, we'll try to follow the standard Python style conventions as -described here: - -* `Style Guide for Python Code `_ - - -Other comments: - -* In a large file, top level classes and functions should be - separated by 2-3 lines to make it easier to separate them visually. -* Use 4 spaces for indentation. -* Keep the ordering of methods the same in classes that have the same - methods. This is particularly true for classes that implement an interface. - -Naming conventions ------------------- - -In terms of naming conventions, we'll follow the guidelines from the `Style -Guide for Python Code`_. - -For all new IPython code (and much existing code is being refactored), we'll -use: - -* All ``lowercase`` module names. - -* ``CamelCase`` for class names. - -* ``lowercase_with_underscores`` for methods, functions, variables and - attributes. - -There are, however, some important exceptions to these rules. In some cases, -IPython code will interface with packages (Twisted, Wx, Qt) that use other -conventions. At some level this makes it impossible to adhere to our own -standards at all times. In particular, when subclassing classes that use other -naming conventions, you must follow their naming conventions. To deal with -cases like this, we propose the following policy: - -* If you are subclassing a class that uses different conventions, use its - naming conventions throughout your subclass. Thus, if you are creating a - Twisted Protocol class, used Twisted's - ``namingSchemeForMethodsAndAttributes.`` - -* All IPython's official interfaces should use our conventions. In some cases - this will mean that you need to provide shadow names (first implement - ``fooBar`` and then ``foo_bar = fooBar``). We want to avoid this at all - costs, but it will probably be necessary at times. But, please use this - sparingly! - -Implementation-specific *private* methods will use -``_single_underscore_prefix``. Names with a leading double underscore will -*only* be used in special cases, as they makes subclassing difficult (such -names are not easily seen by child classes). - -Occasionally some run-in lowercase names are used, but mostly for very short -names or where we are implementing methods very similar to existing ones in a -base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had -established precedent). - -The old IPython codebase has a big mix of classes and modules prefixed with an -explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned -upon, as namespaces offer cleaner prefixing. The only case where this approach -is justified is for classes which are expected to be imported into external -namespaces and a very generic name (like Shell) is too likely to clash with -something else. We'll need to revisit this issue as we clean up and refactor -the code, but in general we should remove as many unnecessary ``IP``/``ip`` -prefixes as possible. However, if a prefix seems absolutely necessary the more -specific ``IPY`` or ``ipy`` are preferred. - -.. _devel_testing: - -Testing system -============== - -It is extremely important that all code contributed to IPython has tests. -Tests should be written as unittests, doctests or as entities that the Nose -[Nose]_ testing package will find. Regardless of how the tests are written, we -will use Nose for discovering and running the tests. Nose will be required to -run the IPython test suite, but will not be required to simply use IPython. - -Tests of Twisted using code need to follow two additional guidelines: - -1. Twisted using tests should be written by subclassing the :class:`TestCase` - class that comes with :mod:`twisted.trial.unittest`. - -2. All :class:`Deferred` instances that are created in the test must be - properly chained and the final one *must* be the return value of the test - method. - -When these two things are done, Nose will be able to run the tests and the -twisted reactor will be handled correctly. - -Each subpackage in IPython should have its own :file:`tests` directory that -contains all of the tests for that subpackage. This allows each subpackage to -be self-contained. A good convention to follow is to have a file named -:file:`test_foo.py` for each module :file:`foo.py` in the package. This makes -it easy to organize the tests, though like most conventions, it's OK to break -it if logic and common sense dictate otherwise. - -If a subpackage has any dependencies beyond the Python standard library, the -tests for that subpackage should be skipped if the dependencies are not -found. This is very important so users don't get tests failing simply because -they don't have dependencies. We ship a set of decorators in the -:mod:`IPython.testing` package to tag tests that may be platform-specific or -otherwise may have restrictions; if the existing ones don't fit your needs, add -a new decorator in that location so other tests can reuse it. - -To run the IPython test suite, use the :command:`iptest` command that is -installed with IPython (if you are using IPython in-place, without installing -it, you can find this script in the :file:`scripts` directory):: - - $ iptest - -This command colects all IPython tests into separate groups, and then calls -either Nose with the proper options and extensions, or Twisted's -:command:`trial`. This ensures that tests that need the Twisted reactor -management facilities execute separate of Nose. If any individual test group -fails, :command:`iptest` will print what you need to type so you can rerun that -particular test group alone for debugging. - -By default, :command:`iptest` runs the entire IPython test -suite (skipping tests that may be platform-specific or which depend on tools -you may not have). But you can also use it to run only one specific test file, -or a specific test function. For example, this will run only the -:file:`test_magic` file from the test suite:: - - $ iptest IPython.tests.test_magic - ---------------------------------------------------------------------- - Ran 10 tests in 0.348s - - OK (SKIP=3) - Deleting object: second_pass - -while the ``path:function`` syntax allows you to select a specific function in -that file to run:: - - $ iptest IPython.tests.test_magic:test_obj_del - ---------------------------------------------------------------------- - Ran 1 test in 0.204s - - OK - -Since :command:`iptest` is based on nosetests, you can pass it any regular -nosetests option. For example, you can use ``--pdb`` or ``--pdb-failures`` to -automatically activate the interactive Pdb debugger on errors or failures. See -the nosetests documentation for further details. - - -A few tips for writing tests ----------------------------- - -You can write tests either as normal test files, using all the conventions that -Nose recognizes, or as doctests. Note that *all* IPython functions should have -at least one example that serves as a doctest, whenever technically feasible. -However, example doctests should only be in the main docstring if they are *a -good example*, i.e. if they convey useful information about the function. If -you simply would like to write a test as a doctest, put it in a separate test -file and write a no-op function whose only purpose is its docstring. - -Note, however, that in a file named :file:`test_X`, functions whose only test -is their docstring (as a doctest) and which have no test functionality of their -own, should be called *doctest_foo* instead of *test_foo*, otherwise they get -double-counted (the empty function call is counted as a test, which just -inflates tests numbers artificially). This restriction does not apply to -functions in files with other names, due to how Nose discovers tests. - -You can use IPython examples in your docstrings. Those can make full use of -IPython functionality (magics, variable substitution, etc), but be careful to -keep them generic enough that they run identically on all Operating Systems. - -The prompts in your doctests can be either of the plain Python ``>>>`` variety -or ``In [1]:`` IPython style. Since this is the IPython system, after all, we -encourage you to use IPython prompts throughout, unless you are illustrating a -specific aspect of the normal prompts (such as the ``%doctest_mode`` magic). - -If a test isn't safe to run inside the main nose process (e.g. because it loads -a GUI toolkit), consider running it in a subprocess and capturing its output -for evaluation and test decision later. Here is an example of how to do it, by -relying on the builtin ``_ip`` object that contains the public IPython api as -defined in :mod:`IPython.ipapi`:: - - def test_obj_del(): - """Test that object's __del__ methods are called on exit.""" - test_dir = os.path.dirname(__file__) - del_file = os.path.join(test_dir,'obj_del.py') - out = _ip.IP.getoutput('ipython %s' % del_file) - nt.assert_equals(out,'object A deleted') - - - -If a doctest contains input whose output you don't want to verify identically -via doctest (random output, an object id, etc), you can mark a docstring with -``#random``. All of these test will have their code executed but no output -checking will be done:: - - >>> 1+3 - junk goes here... # random - - >>> 1+2 - again, anything goes #random - if multiline, the random mark is only needed once. - - >>> 1+2 - You can also put the random marker at the end: - # random - - >>> 1+2 - # random - .. or at the beginning. - -In a case where you want an *entire* docstring to be executed but not verified -(this only serves to check that the code runs without crashing, so it should be -used very sparingly), you can put ``# all-random`` in the docstring. - -.. _devel_config: - -Release checklist -================= - -Most of the release process is automated by the :file:`release` script in the -:file:`tools` directory. This is just a handy reminder for the release manager. - -#. First, run :file:`build_release`, which does all the file checking and - building that the real release script will do. This will let you do test - installations, check that the build procedure runs OK, etc. You may want to - disable a few things like multi-version RPM building while testing, because - otherwise the build takes really long. - -#. Run the release script, which makes the tar.gz, eggs and Win32 .exe - installer. It posts them to the site and registers the release with PyPI. - -#. Updating the website with announcements and links to the updated - changes.txt in html form. Remember to put a short note both on the news - page of the site and on Launcphad. - -#. Drafting a short release announcement with i) highlights and ii) a link to - the html changes.txt. - -#. Make sure that the released version of the docs is live on the site. - -#. Celebrate! - -Porting to 3.0 -============== - -There are no definite plans for porting of IPython to python 3. The major -issue is the dependency on twisted framework for the networking/threading -stuff. It is possible that it the traditional IPython interactive console -could be ported more easily since it has no such dependency. Here are a few -things that will need to be considered when doing such a port especially -if we want to have a codebase that works directly on both 2.x and 3.x. - - 1. The syntax for exceptions changed (PEP 3110). The old - `except exc, var` changed to `except exc as var`. At last - count there was 78 occurences of this usage in the codebase. This - is a particularly problematic issue, because it's not easy to - implement it in a 2.5-compatible way. - -Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we -will likely at some point put out a release that requires strictly 2.6 and -abandons 2.5 compatibility. This will then allow us to port the code to using -:func:`print` as a function, `except exc as var` syntax, etc. But as of -version 0.11 at least, we will retain Python 2.5 compatibility. - - -.. [Bazaar] Bazaar. http://bazaar-vcs.org/ -.. [Launchpad] Launchpad. http://www.launchpad.net/ipython -.. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html -.. [Sphinx] Sphinx. http://sphinx.pocoo.org/ -.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/ diff --git a/docs/source/development/release.txt b/docs/source/development/release.txt new file mode 100644 index 0000000..a7d7d08 --- /dev/null +++ b/docs/source/development/release.txt @@ -0,0 +1,25 @@ +Release checklist +================= + +Most of the release process is automated by the :file:`release` script in the +:file:`tools` directory. This is just a handy reminder for the release manager. + +#. First, run :file:`build_release`, which does all the file checking and + building that the real release script will do. This will let you do test + installations, check that the build procedure runs OK, etc. You may want to + disable a few things like multi-version RPM building while testing, because + otherwise the build takes really long. + +#. Run the release script, which makes the tar.gz, eggs and Win32 .exe + installer. It posts them to the site and registers the release with PyPI. + +#. Updating the website with announcements and links to the updated + changes.txt in html form. Remember to put a short note both on the news + page of the site and on Launcphad. + +#. Drafting a short release announcement with i) highlights and ii) a link to + the html changes.txt. + +#. Make sure that the released version of the docs is live on the site. + +#. Celebrate! \ No newline at end of file diff --git a/docs/source/development/roadmap.txt b/docs/source/development/roadmap.txt index 56ba275..a59c7aa 100644 --- a/docs/source/development/roadmap.txt +++ b/docs/source/development/roadmap.txt @@ -92,3 +92,23 @@ Currently, we have a number of performance issues in :mod:`IPython.kernel`: separate the controller itself into multiple processes, one for the core controller and one each for the controller interfaces. +Porting to 3.0 +============== + +There are no definite plans for porting of IPython to Python 3. The major +issue is the dependency on Twisted framework for the networking/threading +stuff. It is possible that it the traditional IPython interactive console +could be ported more easily since it has no such dependency. Here are a few +things that will need to be considered when doing such a port especially +if we want to have a codebase that works directly on both 2.x and 3.x. + +1. The syntax for exceptions changed (PEP 3110). The old `except exc, var` +changed to `except exc as var`. At last count there was 78 occurrences of this +usage in the code base. This is a particularly problematic issue, because it's +not easy to implement it in a 2.5-compatible way. + +Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we +will likely at some point put out a release that requires strictly 2.6 and +abandons 2.5 compatibility. This will then allow us to port the code to using +:func:`print` as a function, `except exc as var` syntax, etc. But as of +version 0.11 at least, we will retain Python 2.5 compatibility. diff --git a/docs/source/development/testing.txt b/docs/source/development/testing.txt new file mode 100644 index 0000000..436b2de --- /dev/null +++ b/docs/source/development/testing.txt @@ -0,0 +1,194 @@ +.. _testing: + +========================= +Writing and running tests +========================= + +Overview +======== + +It is extremely important that all code contributed to IPython has tests. +Tests should be written as unittests, doctests or other entities that the +IPython test system can detect. See below for more details on this. + +Each subpackage in IPython should have its own :file:`tests` directory that +contains all of the tests for that subpackage. All of the files in the +:file:`tests` directory should have the word "tests" in them to enable +the testing framework to find them. + +If a subpackage has any dependencies beyond the Python standard library, the +tests for that subpackage should be skipped if the dependencies are not found. +This is very important so users don't get tests failing simply because they +don't have dependencies. We are still figuring out the best way for this +to be handled. + +Status +====== + +Currently IPython's testing system is being reworked. In the meantime, +we recommend the following testing practices: + +* To run regular tests, use the :cmd:`nosetests` command on a per file basis: + +.. code-block:: bash + + nosetests -vvs IPython.core.tests.test_component + +* To run Twisted-using tests, use the :cmd:`trial` command on a per file + basis: + +.. code-block:: bash + + trial IPython.kernel + +* For now, regular tests (of non-Twisted using code) should be written as + unit tests. They should be subclasses of :class:`unittest.TestCase`. + +* Tests of Twisted [Twisted]_ using code should be written by subclassing the + ``TestCase`` class that comes with ``twisted.trial.unittest``. + +.. _devel_testing: + +Older material +============== + +It is extremely important that all code contributed to IPython has tests. +Tests should be written as unittests, doctests or as entities that the Nose +[Nose]_ testing package will find. Regardless of how the tests are written, we +will use Nose for discovering and running the tests. Nose will be required to +run the IPython test suite, but will not be required to simply use IPython. + +Tests of Twisted using code need to follow two additional guidelines: + +1. Twisted using tests should be written by subclassing the :class:`TestCase` + class that comes with :mod:`twisted.trial.unittest`. + +2. All :class:`Deferred` instances that are created in the test must be + properly chained and the final one *must* be the return value of the test + method. + +When these two things are done, Nose will be able to run the tests and the +twisted reactor will be handled correctly. + +Each subpackage in IPython should have its own :file:`tests` directory that +contains all of the tests for that subpackage. This allows each subpackage to +be self-contained. A good convention to follow is to have a file named +:file:`test_foo.py` for each module :file:`foo.py` in the package. This makes +it easy to organize the tests, though like most conventions, it's OK to break +it if logic and common sense dictate otherwise. + +If a subpackage has any dependencies beyond the Python standard library, the +tests for that subpackage should be skipped if the dependencies are not +found. This is very important so users don't get tests failing simply because +they don't have dependencies. We ship a set of decorators in the +:mod:`IPython.testing` package to tag tests that may be platform-specific or +otherwise may have restrictions; if the existing ones don't fit your needs, add +a new decorator in that location so other tests can reuse it. + +To run the IPython test suite, use the :command:`iptest` command that is +installed with IPython (if you are using IPython in-place, without installing +it, you can find this script in the :file:`scripts` directory):: + + $ iptest + +This command colects all IPython tests into separate groups, and then calls +either Nose with the proper options and extensions, or Twisted's +:command:`trial`. This ensures that tests that need the Twisted reactor +management facilities execute separate of Nose. If any individual test group +fails, :command:`iptest` will print what you need to type so you can rerun that +particular test group alone for debugging. + +By default, :command:`iptest` runs the entire IPython test +suite (skipping tests that may be platform-specific or which depend on tools +you may not have). But you can also use it to run only one specific test file, +or a specific test function. For example, this will run only the +:file:`test_magic` file from the test suite:: + + $ iptest IPython.tests.test_magic + ---------------------------------------------------------------------- + Ran 10 tests in 0.348s + + OK (SKIP=3) + Deleting object: second_pass + +while the ``path:function`` syntax allows you to select a specific function in +that file to run:: + + $ iptest IPython.tests.test_magic:test_obj_del + ---------------------------------------------------------------------- + Ran 1 test in 0.204s + + OK + +Since :command:`iptest` is based on nosetests, you can pass it any regular +nosetests option. For example, you can use ``--pdb`` or ``--pdb-failures`` to +automatically activate the interactive Pdb debugger on errors or failures. See +the nosetests documentation for further details. + + +A few tips for writing tests +---------------------------- + +You can write tests either as normal test files, using all the conventions that +Nose recognizes, or as doctests. Note that *all* IPython functions should have +at least one example that serves as a doctest, whenever technically feasible. +However, example doctests should only be in the main docstring if they are *a +good example*, i.e. if they convey useful information about the function. If +you simply would like to write a test as a doctest, put it in a separate test +file and write a no-op function whose only purpose is its docstring. + +Note, however, that in a file named :file:`test_X`, functions whose only test +is their docstring (as a doctest) and which have no test functionality of their +own, should be called *doctest_foo* instead of *test_foo*, otherwise they get +double-counted (the empty function call is counted as a test, which just +inflates tests numbers artificially). This restriction does not apply to +functions in files with other names, due to how Nose discovers tests. + +You can use IPython examples in your docstrings. Those can make full use of +IPython functionality (magics, variable substitution, etc), but be careful to +keep them generic enough that they run identically on all Operating Systems. + +The prompts in your doctests can be either of the plain Python ``>>>`` variety +or ``In [1]:`` IPython style. Since this is the IPython system, after all, we +encourage you to use IPython prompts throughout, unless you are illustrating a +specific aspect of the normal prompts (such as the ``%doctest_mode`` magic). + +If a test isn't safe to run inside the main nose process (e.g. because it loads +a GUI toolkit), consider running it in a subprocess and capturing its output +for evaluation and test decision later. Here is an example of how to do it, by +relying on the builtin ``_ip`` object that contains the public IPython api as +defined in :mod:`IPython.ipapi`:: + + def test_obj_del(): + """Test that object's __del__ methods are called on exit.""" + test_dir = os.path.dirname(__file__) + del_file = os.path.join(test_dir,'obj_del.py') + out = _ip.IP.getoutput('ipython %s' % del_file) + nt.assert_equals(out,'object A deleted') + + + +If a doctest contains input whose output you don't want to verify identically +via doctest (random output, an object id, etc), you can mark a docstring with +``#random``. All of these test will have their code executed but no output +checking will be done:: + + >>> 1+3 + junk goes here... # random + + >>> 1+2 + again, anything goes #random + if multiline, the random mark is only needed once. + + >>> 1+2 + You can also put the random marker at the end: + # random + + >>> 1+2 + # random + .. or at the beginning. + +In a case where you want an *entire* docstring to be executed but not verified +(this only serves to check that the code runs without crashing, so it should be +used very sparingly), you can put ``# all-random`` in the docstring. + diff --git a/docs/source/faq.txt b/docs/source/faq.txt index c30adb1..60dc3bf 100644 --- a/docs/source/faq.txt +++ b/docs/source/faq.txt @@ -91,6 +91,3 @@ handling the data movement. Here are some ideas: 5. See if you can pass data directly between engines using MPI. -Isn't Python slow to be used for high-performance parallel computing? ---------------------------------------------------------------------- - diff --git a/docs/source/index.txt b/docs/source/index.txt index a2874a8..243bdec 100644 --- a/docs/source/index.txt +++ b/docs/source/index.txt @@ -7,8 +7,7 @@ IPython Documentation :Release: |release| :Date: |today| -Welcome to the official IPython documentation. This document describes the -various parts of IPython that are relevant to both users and developers. +Welcome to the official IPython documentation. Contents ======== diff --git a/docs/source/install/install.txt b/docs/source/install/install.txt index d513d79..e005a50 100644 --- a/docs/source/install/install.txt +++ b/docs/source/install/install.txt @@ -34,16 +34,20 @@ Quickstart If you have :mod:`setuptools` installed and you are on OS X or Linux (not Windows), the following will download and install IPython *and* the main -optional dependencies:: +optional dependencies: - $ easy_install ipython[kernel,security,test] +.. code-block:: bash + + easy_install ipython[kernel,security,test] This will get Twisted, zope.interface and Foolscap, which are needed for IPython's parallel computing features as well as the nose package, which will enable you to run IPython's test suite. To run IPython's test suite, use the -:command:`iptest` command:: +:command:`iptest` command: + +.. code-block:: bash - $ iptest + iptest Read on for more specific details and instructions for Windows. @@ -62,9 +66,11 @@ Installation using easy_install ------------------------------- If you have :mod:`setuptools` installed, the easiest way of getting IPython is -to simple use :command:`easy_install`:: +to simple use :command:`easy_install`: - $ easy_install ipython +.. code-block:: bash + + easy_install ipython That's it. @@ -73,11 +79,13 @@ Installation from source 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 -`_. Then do the following:: +`_. Then do the following: + +.. code-block:: bash - $ tar -xzf ipython.tar.gz - $ cd ipython - $ python setup.py install + tar -xzf ipython.tar.gz + cd ipython + python setup.py install 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`. @@ -98,7 +106,7 @@ use any of the following alternatives: 3. Install from source, but using :mod:`setuptools` (``python setupegg.py install``). -IPython by default runs in a termninal window, but the normal terminal +IPython by default runs in a terminal window, but the normal terminal application supplied by Microsoft Windows is very primitive. You may want to download the excellent and free Console_ application instead, which is a far superior tool. You can even configure Console to give you by default an @@ -113,26 +121,32 @@ Installing the development version It is also possible to install the development version of IPython from our `Bazaar `_ source code repository. To do this you will -need to have Bazaar installed on your system. Then just do:: +need to have Bazaar installed on your system. Then just do: - $ bzr branch lp:ipython - $ cd ipython - $ python setup.py install +.. code-block:: bash + + bzr branch lp:ipython + cd ipython + python setup.py install 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. 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:: +step by: + +.. code-block:: bash - $ python setupegg.py develop + python setupegg.py develop 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:: +just do: + +.. code-block:: bash - $ bzr pull + bzr pull Basic optional dependencies =========================== @@ -165,9 +179,11 @@ many of the issues related to the differences between readline and libedit have been resolved. For many users, libedit may be sufficient. 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):: +working :mod:`readline` module, just do (with :mod:`setuptools` installed): - $ easy_install readline +.. code-block:: bash + + easy_install readline .. note: @@ -190,28 +206,35 @@ nose 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`:: +simplest way of getting nose, is to use :command:`easy_install`: + +.. code-block:: bash - $ easy_install nose + easy_install nose -Another way of getting this is to do:: +Another way of getting this is to do: - $ easy_install ipython[test] +.. code-block:: bash + + easy_install ipython[test] For more installation options, see the `nose website `_. Once you have nose -installed, you can run IPython's test suite using the iptest command:: +installed, you can run IPython's test suite using the iptest command: - $ iptest +.. code-block:: bash + iptest pexpect ------- The `pexpect `_ package is used in IPython's -:command:`irunner` script. On Unix platforms (including OS X), just do:: +:command:`irunner` script. On Unix platforms (including OS X), just do: + +.. code-block:: bash - $ easy_install pexpect + easy_install pexpect Windows users are out of luck as pexpect does not run there. @@ -227,36 +250,45 @@ features require a number of additional packages: * Foolscap (a nice, secure network protocol) * pyOpenSSL (security for network connections) -On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do:: +On a Unix style platform (including OS X), if you want to use +:mod:`setuptools`, you can just do: - $ easy_install ipython[kernel] # the first three - $ easy_install ipython[security] # pyOpenSSL +.. code-block:: bash + + easy_install ipython[kernel] # the first three + easy_install ipython[security] # pyOpenSSL zope.interface and Twisted -------------------------- Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking related things. On Unix style platforms (including OS X), the simplest way of -getting the these is to use :command:`easy_install`:: +getting the these is to use :command:`easy_install`: + +.. code-block:: bash - $ easy_install zope.interface - $ easy_install Twisted + easy_install zope.interface + easy_install Twisted -Of course, you can also download the source tarballs from the `Twisted website -`_ and the `zope.interface page at PyPI +Of course, you can also download the source tarballs from the Twisted website +[Twisted]_ and the `zope.interface page at PyPI `_ and do the usual ``python setup.py install`` if you prefer. -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. +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. Foolscap -------- Foolscap [Foolscap]_ uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features. -On all platforms a simple:: +On all platforms a simple: + +.. code-block:: bash - $ easy_install foolscap + easy_install foolscap should work. You can also download the source tarballs from the `Foolscap website `_ and do ``python setup.py install`` @@ -265,14 +297,16 @@ if you prefer. pyOpenSSL --------- -IPython requires an older version of pyOpenSSL [pyOpenSSL]_ (0.6 rather than -the current 0.7). There are a couple of options for getting this: +IPython does not work with version 0.7 of pyOpenSSL [pyOpenSSL]_. It is known +to work with version 0.6 and will likely work with the more recent 0.8 and 0.9 +versions. There are a couple of options for getting this: -1. Most Linux distributions have packages for pyOpenSSL. -2. The built-in Python 2.5 on OS X 10.5 already has it installed. -3. There are source tarballs on the pyOpenSSL website. On Unix-like - platforms, these can be built using ``python seutp.py install``. -4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website `_. +1. Most Linux distributions have packages for pyOpenSSL. +2. The built-in Python 2.5 on OS X 10.5 already has it installed. +3. There are source tarballs on the pyOpenSSL website. On Unix-like + platforms, these can be built using ``python seutp.py install``. +4. There is also a binary ``.exe`` Windows installer on the + `pyOpenSSL website `_. Dependencies for IPython.frontend (the IPython GUI) =================================================== @@ -280,11 +314,11 @@ Dependencies for IPython.frontend (the IPython GUI) wxPython -------- -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 +Starting with IPython 0.9, IPython has a new :mod:`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 `_. .. [Twisted] Twisted matrix. http://twistedmatrix.org diff --git a/docs/source/interactive/extension_api.txt b/docs/source/interactive/extension_api.txt deleted file mode 100644 index 5c367aa..0000000 --- a/docs/source/interactive/extension_api.txt +++ /dev/null @@ -1,253 +0,0 @@ -===================== -IPython extension API -===================== - -IPython api (defined in IPython/ipapi.py) is the public api that -should be used for - - * Configuration of user preferences (.ipython/ipy_user_conf.py) - * Creating new profiles (.ipython/ipy_profile_PROFILENAME.py) - * Writing extensions - -Note that by using the extension api for configuration (editing -ipy_user_conf.py instead of ipythonrc), you get better validity checks -and get richer functionality - for example, you can import an -extension and call functions in it to configure it for your purposes. - -For an example extension (the 'sh' profile), see -IPython/extensions/ipy_profile_sh.py. - -For the last word on what's available, see the source code of -IPython/ipapi.py. - - -Getting started -=============== - -If you want to define an extension, create a normal python module that -can be imported. The module will access IPython functionality through -the 'ip' object defined below. - -If you are creating a new profile (e.g. foobar), name the module as -'ipy_profile_foobar.py' and put it in your ~/.ipython directory. Then, -when you start ipython with the '-p foobar' argument, the module is -automatically imported on ipython startup. - -If you are just doing some per-user configuration, you can either - - * Put the commands directly into ipy_user_conf.py. - - * Create a new module with your customization code and import *that* - module in ipy_user_conf.py. This is preferable to the first approach, - because now you can reuse and distribute your customization code. - -Getting a handle to the api -=========================== - -Put this in the start of your module:: - - #!python - import IPython.ipapi - ip = IPython.ipapi.get() - -The 'ip' object will then be used for accessing IPython -functionality. 'ip' will mean this api object in all the following -code snippets. The same 'ip' that we just acquired is always -accessible in interactive IPython sessions by the name _ip - play with -it like this:: - - [~\_ipython]|81> a = 10 - [~\_ipython]|82> _ip.e - _ip.ev _ip.ex _ip.expose_magic - [~\_ipython]|82> _ip.ev('a+13') - <82> 23 - -The _ip object is also used in some examples in this document - it can -be substituted by 'ip' in non-interactive use. - -Changing options -================ - -The ip object has 'options' attribute that can be used te get/set -configuration options (just as in the ipythonrc file):: - - o = ip.options - o.autocall = 2 - o.automagic = 1 - -Executing statements in IPython namespace with 'ex' and 'ev' -============================================================ - -Often, you want to e.g. import some module or define something that -should be visible in IPython namespace. Use ``ip.ev`` to -*evaluate* (calculate the value of) expression and ``ip.ex`` to -'''execute''' a statement:: - - # path module will be visible to the interactive session - ip.ex("from path import path" ) - - # define a handy function 'up' that changes the working directory - - ip.ex('import os') - ip.ex("def up(): os.chdir('..')") - - - # _i2 has the input history entry #2, print its value in uppercase. - print ip.ev('_i2.upper()') - -Accessing the IPython namespace -=============================== - -ip.user_ns attribute has a dictionary containing the IPython global -namespace (the namespace visible in the interactive session). - -:: - - [~\_ipython]|84> tauno = 555 - [~\_ipython]|85> _ip.user_ns['tauno'] - <85> 555 - -Defining new magic commands -=========================== - -The following example defines a new magic command, %impall. What the -command does should be obvious:: - - def doimp(self, arg): - ip = self.api - ip.ex("import %s; reload(%s); from %s import *" % ( - arg,arg,arg) - ) - - ip.expose_magic('impall', doimp) - -Things to observe in this example: - - * Define a function that implements the magic command using the - ipapi methods defined in this document - * The first argument of the function is 'self', i.e. the - interpreter object. It shouldn't be used directly. however. - The interpreter object is probably *not* going to remain stable - through IPython versions. - * Access the ipapi through 'self.api' instead of the global 'ip' object. - * All the text following the magic command on the command line is - contained in the second argument - * Expose the magic by ip.expose_magic() - - -Calling magic functions and system commands -=========================================== - -Use ip.magic() to execute a magic function, and ip.system() to execute -a system command:: - - # go to a bookmark - ip.magic('%cd -b relfiles') - - # execute 'ls -F' system command. Interchangeable with os.system('ls'), really. - ip.system('ls -F') - -Launching IPython instance from normal python code -================================================== - -Use ipapi.launch_new_instance() with an argument that specifies the -namespace to use. This can be useful for trivially embedding IPython -into your program. Here's an example of normal python program test.py -('''without''' an existing IPython session) that launches an IPython -interpreter and regains control when the interpreter is exited:: - - [ipython]|1> cat test.py - my_ns = dict( - kissa = 15, - koira = 16) - import IPython.ipapi - print "launching IPython instance" - IPython.ipapi.launch_new_instance(my_ns) - print "Exited IPython instance!" - print "New vals:",my_ns['kissa'], my_ns['koira'] - -And here's what it looks like when run (note how we don't start it -from an ipython session):: - - Q:\ipython>python test.py - launching IPython instance - Py 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] IPy 0.7.3b3.r1975 - [ipython]|1> kissa = 444 - [ipython]|2> koira = 555 - [ipython]|3> Exit - Exited IPython instance! - New vals: 444 555 - -Accessing unexposed functionality -================================= - -There are still many features that are not exposed via the ipapi. If -you can't avoid using them, you can use the functionality in -InteractiveShell object (central IPython session class, defined in -iplib.py) through ip.IP. - -For example:: - - [~]|7> _ip.IP.expand_aliases('np','myfile.py') - <7> 'c:/opt/Notepad++/notepad++.exe myfile.py' - [~]|8> - -Still, it's preferable that if you encounter such a feature, contact -the IPython team and request that the functionality be exposed in a -future version of IPython. Things not in ipapi are more likely to -change over time. - -Provided extensions -=================== - -You can see the list of available extensions (and profiles) by doing -``import ipy_``. Some extensions don't have the ``ipy_`` prefix in -module name, so you may need to see the contents of IPython/extensions -folder to see what's available. - -You can see a brief documentation of an extension by looking at the -module docstring:: - - [c:p/ipython_main]|190> import ipy_fsops - [c:p/ipython_main]|191> ipy_fsops? - - ... - - Docstring: - File system operations - - Contains: Simple variants of normal unix shell commands (icp, imv, irm, - imkdir, igrep). - -You can also install your own extensions - the recommended way is to -just copy the module to ~/.ipython. Extensions are typically enabled -by just importing them (e.g. in ipy_user_conf.py), but some extensions -require additional steps, for example:: - - [c:p]|192> import ipy_traits_completer - [c:p]|193> ipy_traits_completer.activate() - -Note that extensions, even if provided in the stock IPython -installation, are not guaranteed to have the same requirements as the -rest of IPython - an extension may require external libraries or a -newer version of Python than what IPython officially requires. An -extension may also be under a more restrictive license than IPython -(e.g. ipy_bzr is under GPL). - -Just for reference, the list of bundled extensions at the time of -writing is below: - -astyle.py clearcmd.py envpersist.py ext_rescapture.py ibrowse.py -igrid.py InterpreterExec.py InterpreterPasteInput.py ipipe.py -ipy_app_completers.py ipy_autoreload.py ipy_bzr.py ipy_completers.py -ipy_constants.py ipy_defaults.py ipy_editors.py ipy_exportdb.py -ipy_extutil.py ipy_fsops.py ipy_gnuglobal.py ipy_kitcfg.py -ipy_legacy.py ipy_leo.py ipy_p4.py ipy_profile_doctest.py -ipy_profile_none.py ipy_profile_scipy.py ipy_profile_sh.py -ipy_profile_zope.py ipy_pydb.py ipy_rehashdir.py ipy_render.py -ipy_server.py ipy_signals.py ipy_stock_completers.py -ipy_system_conf.py ipy_traits_completer.py ipy_vimserver.py -ipy_which.py ipy_workdir.py jobctrl.py ledit.py numeric_formats.py -PhysicalQInput.py PhysicalQInteractive.py pickleshare.py -pspersistence.py win32clip.py __init__.py - diff --git a/docs/source/interactive/index.txt b/docs/source/interactive/index.txt index 0e0dff9..7e398ef 100644 --- a/docs/source/interactive/index.txt +++ b/docs/source/interactive/index.txt @@ -8,5 +8,5 @@ Using IPython for interactive work tutorial.txt reference.txt shell.txt - extension_api.txt + diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index c1afa10..20bdecb 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -2,6 +2,14 @@ IPython reference ================= +.. warning:: + + As of the 0.11 version of IPython, some of the features and APIs + described in this section have been deprecated or are broken. Our plan + is to continue to support these features, but they need to be updated + to take advantage of recent API changes. Furthermore, this section + of the documentation need to be updated to reflect all of these changes. + .. _command_line_options: Command-line usage diff --git a/docs/source/interactive/shell.txt b/docs/source/interactive/shell.txt index 0c39d16..2f406f2 100644 --- a/docs/source/interactive/shell.txt +++ b/docs/source/interactive/shell.txt @@ -4,6 +4,14 @@ IPython as a system shell ========================= +.. warning:: + + As of the 0.11 version of IPython, some of the features and APIs + described in this section have been deprecated or are broken. Our plan + is to continue to support these features, but they need to be updated + to take advantage of recent API changes. Furthermore, this section + of the documentation need to be updated to reflect all of these changes. + Overview ======== diff --git a/docs/source/interactive/tutorial.txt b/docs/source/interactive/tutorial.txt index 21381d7..1f5ccda 100644 --- a/docs/source/interactive/tutorial.txt +++ b/docs/source/interactive/tutorial.txt @@ -4,6 +4,14 @@ Quick IPython tutorial ====================== +.. warning:: + + As of the 0.11 version of IPython, some of the features and APIs + described in this section have been deprecated or are broken. Our plan + is to continue to support these features, but they need to be updated + to take advantage of recent API changes. Furthermore, this section + of the documentation need to be updated to reflect all of these changes. + IPython can be used as an improved replacement for the Python prompt, and for that you don't really need to read any more of this manual. But in this section we'll try to summarize a few tips on how to make the diff --git a/docs/source/overview.txt b/docs/source/overview.txt index a3250d4..228d2a3 100644 --- a/docs/source/overview.txt +++ b/docs/source/overview.txt @@ -219,9 +219,9 @@ Portability and Python requirements ----------------------------------- As of the 0.11 release, IPython works with either Python 2.5 or 2.6. -Versions 0.9 and 0.10 worked with Python 2.4 as well. We have not begun -the test and port IPython to 3.0. Our plan is to gradually drop Python 2.5 -support and then begin the transition to strict 2.6 and 3.0. +Versions 0.9 and 0.10 worked with Python 2.4 as well. We have not yet begun +to test and port IPython to Python 3. Our plan is to gradually drop Python 2.5 +support and then begin the transition to strict 2.6 and 3. IPython is known to work on the following operating systems: diff --git a/docs/source/whatsnew/index.txt b/docs/source/whatsnew/index.txt index c36e178..ed606f6 100644 --- a/docs/source/whatsnew/index.txt +++ b/docs/source/whatsnew/index.txt @@ -12,6 +12,11 @@ What's new in IPython ===================== +This section documents the changes that have been made in various versions of +IPython. Users should consult these pages to learn about new features, bug +fixes and backwards incompatibilities. Developers should summarize the +development work they do here in a user friendly format. + .. toctree:: :maxdepth: 1