From dc983636bf478b69d106dcfdba65b412e1b16e3d 2009-09-28 05:57:44 From: Brian Granger Date: 2009-09-28 05:57:44 Subject: [PATCH] Major work on the documentation. * Everything is cleaned up. * Outdated things have been re-written or removed. * Full documentation about the new config system has been added. * The developer guide has been re-organized and re-written where appropriate. --- diff --git a/IPython/config/default/ipython_config.py b/IPython/config/default/ipython_config.py index 413c1e3..63c0b54 100644 --- a/IPython/config/default/ipython_config.py +++ b/IPython/config/default/ipython_config.py @@ -140,7 +140,7 @@ c.Global.log_level = 20 # AliasManager options #----------------------------------------------------------------------------- -# Do this to enable all defaults +# Do this to disable all defaults # c.AliasManager.default_aliases = [] # c.AliasManager.user_aliases = [ diff --git a/IPython/core/component.py b/IPython/core/component.py index 752f227..9e72790 100644 --- a/IPython/core/component.py +++ b/IPython/core/component.py @@ -144,8 +144,8 @@ def masquerade_as(instance, cls): masquerade as another. Python, being duck typed, allows this by default. But, instances of components are tracked by their class type. - After calling this, cls.get_instances() will return ``instance``. This - does not, however, cause isinstance(instance, cls) to return ``True``. + After calling this, ``cls.get_instances()`` will return ``instance``. This + does not, however, cause ``isinstance(instance, cls)`` to return ``True``. Parameters ---------- diff --git a/IPython/core/prefilter.py b/IPython/core/prefilter.py index 0ce6ebd..4be6e5b 100644 --- a/IPython/core/prefilter.py +++ b/IPython/core/prefilter.py @@ -207,7 +207,7 @@ class PrefilterManager(Component): Users or developers can change the priority or enabled attribute of transformers or checkers, but they must call the :meth:`sort_checkers` - or :meth`sort_transformers` method after changing the priority. + or :meth:`sort_transformers` method after changing the priority. """ multi_line_specials = CBool(True, config=True) diff --git a/IPython/utils/traitlets.py b/IPython/utils/traitlets.py index 98c0613..960c19c 100644 --- a/IPython/utils/traitlets.py +++ b/IPython/utils/traitlets.py @@ -439,17 +439,17 @@ class HasTraitlets(object): Parameters ---------- - handler : callable - A callable that is called when a traitlet changes. Its - signature can be handler(), handler(name), handler(name, new) - or handler(name, old, new). - name : list, str, None - If None, the handler will apply to all traitlets. If a list - of str, handler will apply to all names in the list. If a - str, the handler will apply just to that name. - remove : bool - If False (the default), then install the handler. If True - then unintall it. + handler : callable + A callable that is called when a traitlet changes. Its + signature can be handler(), handler(name), handler(name, new) + or handler(name, old, new). + name : list, str, None + If None, the handler will apply to all traitlets. If a list + of str, handler will apply to all names in the list. If a + str, the handler will apply just to that name. + remove : bool + If False (the default), then install the handler. If True + then unintall it. """ if remove: names = parse_notifier_name(name) diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 1462400..0667e7e 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -4,7 +4,7 @@ {% block rootrellink %}
  • home| 
  • search| 
    • -
  • what's new »
    • +
  • documentation »
    • {% endblock %} diff --git a/docs/source/config/customization.txt b/docs/source/config/customization.txt deleted file mode 100644 index 2d66648..0000000 --- a/docs/source/config/customization.txt +++ /dev/null @@ -1,287 +0,0 @@ -.. _customization: - -======================== -Customization of IPython -======================== - -There are 2 ways to configure IPython - the old way of using ipythonrc -files (an INI-file like format), and the new way that involves editing -your ipy_user_conf.py. Both configuration systems work at the same -time, so you can set your options in both, but if you are hesitating -about which alternative to choose, we recommend the ipy_user_conf.py -approach, as it will give you more power and control in the long -run. However, there are few options such as pylab_import_all that can -only be specified in ipythonrc file or command line - the reason for -this is that they are needed before IPython has been started up, and -the IPApi object used in ipy_user_conf.py is not yet available at that -time. A hybrid approach of specifying a few options in ipythonrc and -doing the more advanced configuration in ipy_user_conf.py is also -possible. - -.. _ipythonrc: - -The ipythonrc approach -====================== - -As we've already mentioned, IPython reads a configuration file which can -be specified at the command line (-rcfile) or which by default is -assumed to be called ipythonrc. Such a file is looked for in the current -directory where IPython is started and then in your IPYTHONDIR, which -allows you to have local configuration files for specific projects. In -this section we will call these types of configuration files simply -rcfiles (short for resource configuration file). - -The syntax of an rcfile is one of key-value pairs separated by -whitespace, one per line. Lines beginning with a # are ignored as -comments, but comments can not be put on lines with data (the parser is -fairly primitive). Note that these are not python files, and this is -deliberate, because it allows us to do some things which would be quite -tricky to implement if they were normal python files. - -First, an rcfile can contain permanent default values for almost all command -line options (except things like -help or -Version). :ref:`This section -` contains a description of all command-line -options. However, values you explicitly specify at the command line override -the values defined in the rcfile. - -Besides command line option values, the rcfile can specify values for -certain extra special options which are not available at the command -line. These options are briefly described below. - -Each of these options may appear as many times as you need it in the file. - - * include ...: you can name other rcfiles you want - to recursively load up to 15 levels (don't use the <> brackets in - your names!). This feature allows you to define a 'base' rcfile - with general options and special-purpose files which can be loaded - only when needed with particular configuration options. To make - this more convenient, IPython accepts the -profile option - (abbreviates to -p ) which tells it to look for an rcfile - named ipythonrc-. - * import_mod ...: import modules with 'import - ,,...' - * import_some ...: import functions with 'from - import ,,...' - * import_all ...: for each module listed import - functions with ``from import *``. - * execute : give any single-line python code to be - executed. - * execfile : execute the python file given with an - 'execfile(filename)' command. Username expansion is performed on - the given names. So if you need any amount of extra fancy - customization that won't fit in any of the above 'canned' options, - you can just put it in a separate python file and execute it. - * alias : this is equivalent to calling - '%alias ' at the IPython command line. This way, from - within IPython you can do common system tasks without having to - exit it or use the ! escape. IPython isn't meant to be a shell - replacement, but it is often very useful to be able to do things - with files while testing code. This gives you the flexibility to - have within IPython any aliases you may be used to under your - normal system shell. - -ipy_user_conf.py -================ - -There should be a simple template ipy_user_conf.py file in your -~/.ipython directory. It is a plain python module that is imported -during IPython startup, so you can do pretty much what you want there -- import modules, configure extensions, change options, define magic -commands, put variables and functions in the IPython namespace, -etc. You use the IPython extension api object, acquired by -IPython.ipapi.get() and documented in the "IPython extension API" -chapter, to interact with IPython. A sample ipy_user_conf.py is listed -below for reference:: - - # Most of your config files and extensions will probably start - # with this import - - import IPython.ipapi - ip = IPython.ipapi.get() - - # You probably want to uncomment this if you did %upgrade -nolegacy - # import ipy_defaults - - import os - - def main(): - - #ip.dbg.debugmode = True - ip.dbg.debug_stack() - - # uncomment if you want to get ipython -p sh behaviour - # without having to use command line switches - import ipy_profile_sh - import jobctrl - - # Configure your favourite editor? - # Good idea e.g. for %edit os.path.isfile - - #import ipy_editors - - # Choose one of these: - - #ipy_editors.scite() - #ipy_editors.scite('c:/opt/scite/scite.exe') - #ipy_editors.komodo() - #ipy_editors.idle() - # ... or many others, try 'ipy_editors??' after import to see them - - # Or roll your own: - #ipy_editors.install_editor("c:/opt/jed +$line $file") - - - o = ip.options - # An example on how to set options - #o.autocall = 1 - o.system_verbose = 0 - - #import_all("os sys") - #execf('~/_ipython/ns.py') - - - # -- prompt - # A different, more compact set of prompts from the default ones, that - # always show your current location in the filesystem: - - #o.prompt_in1 = r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Normal\n\C_Green|\#>' - #o.prompt_in2 = r'.\D: ' - #o.prompt_out = r'[\#] ' - - # Try one of these color settings if you can't read the text easily - # autoexec is a list of IPython commands to execute on startup - #o.autoexec.append('%colors LightBG') - #o.autoexec.append('%colors NoColor') - o.autoexec.append('%colors Linux') - - - # some config helper functions you can use - def import_all(modules): - """ Usage: import_all("os sys") """ - for m in modules.split(): - ip.ex("from %s import *" % m) - - def execf(fname): - """ Execute a file in user namespace """ - ip.ex('execfile("%s")' % os.path.expanduser(fname)) - - main() - -.. _Prompts: - -Fine-tuning your prompt -======================= - -IPython's prompts can be customized using a syntax similar to that of -the bash shell. Many of bash's escapes are supported, as well as a few -additional ones. We list them below:: - - \# - the prompt/history count number. This escape is automatically - wrapped in the coloring codes for the currently active color scheme. - \N - the 'naked' prompt/history count number: this is just the number - itself, without any coloring applied to it. This lets you produce - numbered prompts with your own colors. - \D - the prompt/history count, with the actual digits replaced by dots. - Used mainly in continuation prompts (prompt_in2) - \w - the current working directory - \W - the basename of current working directory - \Xn - where $n=0\ldots5.$ The current working directory, with $HOME - replaced by ~, and filtered out to contain only $n$ path elements - \Yn - Similar to \Xn, but with the $n+1$ element included if it is ~ (this - is similar to the behavior of the %cn escapes in tcsh) - \u - the username of the current user - \$ - if the effective UID is 0, a #, otherwise a $ - \h - the hostname up to the first '.' - \H - the hostname - \n - a newline - \r - a carriage return - \v - IPython version string - -In addition to these, ANSI color escapes can be insterted into the -prompts, as \C_ColorName. The list of valid color names is: Black, Blue, -Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, -LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White, -Yellow. - -Finally, IPython supports the evaluation of arbitrary expressions in -your prompt string. The prompt strings are evaluated through the syntax -of PEP 215, but basically you can use $x.y to expand the value of x.y, -and for more complicated expressions you can use braces: ${foo()+x} will -call function foo and add to it the value of x, before putting the -result into your prompt. For example, using -prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' -will print the result of the uptime command on each prompt (assuming the -commands module has been imported in your ipythonrc file). - - - Prompt examples - -The following options in an ipythonrc file will give you IPython's -default prompts:: - - prompt_in1 'In [\#]:' - prompt_in2 ' .\D.:' - prompt_out 'Out[\#]:' - -which look like this:: - - In [1]: 1+2 - Out[1]: 3 - - In [2]: for i in (1,2,3): - ...: print i, - ...: - 1 2 3 - -These will give you a very colorful prompt with path information:: - - #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' - prompt_in2 ' ..\D>' - prompt_out '<\#>' - -which look like this:: - - fperez[~/ipython]1> 1+2 - <1> 3 - fperez[~/ipython]2> for i in (1,2,3): - ...> print i, - ...> - 1 2 3 - - -.. _Profiles: - -IPython profiles -================ - -As we already mentioned, IPython supports the -profile command-line option (see -:ref:`here `). A profile is nothing more than a -particular configuration file like your basic ipythonrc one, but with -particular customizations for a specific purpose. When you start IPython with -'ipython -profile ', it assumes that in your IPYTHONDIR there is a file -called ipythonrc- or ipy_profile_.py, and loads it instead of the -normal ipythonrc. - -This system allows you to maintain multiple configurations which load -modules, set options, define functions, etc. suitable for different -tasks and activate them in a very simple manner. In order to avoid -having to repeat all of your basic options (common things that don't -change such as your color preferences, for example), any profile can -include another configuration file. The most common way to use profiles -is then to have each one include your basic ipythonrc file as a starting -point, and then add further customizations. - diff --git a/docs/source/config/editors.txt b/docs/source/config/editors.txt new file mode 100644 index 0000000..bda308b --- /dev/null +++ b/docs/source/config/editors.txt @@ -0,0 +1,117 @@ +.. _editors: + +==================== +Editor configuration +==================== + +IPython can integrate with text editors in a number of different ways: + +* Editors (such as (X)Emacs [Emacs]_, vim [vim]_ and TextMate [TextMate]_) can + send code to IPython for execution. + +* IPython's ``%edit`` magic command can open an editor of choice to edit + a code block. + +The %edit command (and its alias %ed) will invoke the editor set in your +environment as :envvar:`EDITOR`. If this variable is not set, it will default +to vi under Linux/Unix and to notepad under Windows. You may want to set this +variable properly and to a lightweight editor which doesn't take too long to +start (that is, something other than a new instance of Emacs). This way you +can edit multi-line code quickly and with the power of a real editor right +inside IPython. + +You can also control the editor via the commmand-line option '-editor' or in +your configuration file, by setting the :attr:`InteractiveShell.editor` +configuration attribute. + +TextMate +======== + +Currently, TextMate support in IPython is broken. It used to work well, +but the code has been moved to :mod:`IPython.quarantine` until it is updated. + +vim configuration +================= + +Currently, vim support in IPython is broken. Like the TextMate code, +the vim support code has been moved to :mod:`IPython.quarantine` until it +is updated. + +.. _emacs: + +(X)Emacs +======== + +Editor +====== + +If you are a dedicated Emacs user, and want to use Emacs when IPython's +``%edit`` magic command is called you should set up the Emacs server so that +new requests are handled by the original process. This means that almost no +time is spent in handling the request (assuming an Emacs process is already +running). For this to work, you need to set your EDITOR environment variable +to 'emacsclient'. The code below, supplied by Francois Pinard, can then be +used in your :file:`.emacs` file to enable the server:: + + (defvar server-buffer-clients) + (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) + (server-start) + (defun fp-kill-server-with-buffer-routine () + (and server-buffer-clients (server-done))) + (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) + +Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, +currently (X)Emacs and IPython get along very well in other ways. + +.. note:: + + You will need to use a recent enough version of :file:`python-mode.el`, + along with the file :file:`ipython.el`. You can check that the version you + have of :file:`python-mode.el` is new enough by either looking at the + revision number in the file itself, or asking for it in (X)Emacs via ``M-x + py-version``. Versions 4.68 and newer contain the necessary fixes for + proper IPython support. + +The file :file:`ipython.el` is included with the IPython distribution, in the +directory :file:`docs/emacs`. Once you put these files in your Emacs path, all +you need in your :file:`.emacs` file is:: + + (require 'ipython) + +This should give you full support for executing code snippets via +IPython, opening IPython as your Python shell via ``C-c !``, etc. + +You can customize the arguments passed to the IPython instance at startup by +setting the ``py-python-command-args`` variable. For example, to start always +in ``pylab`` mode with hardcoded light-background colors, you can use:: + + (setq py-python-command-args '("-pylab" "-colors" "LightBG")) + +If you happen to get garbage instead of colored prompts as described in +the previous section, you may need to set also in your :file:`.emacs` file:: + + (setq ansi-color-for-comint-mode t) + +Notes on emacs support: + +* There is one caveat you should be aware of: you must start the IPython shell + before attempting to execute any code regions via ``C-c |``. Simply type + ``C-c !`` to start IPython before passing any code regions to the + interpreter, and you shouldn't experience any problems. This is due to a bug + in Python itself, which has been fixed for Python 2.3, but exists as of + Python 2.2.2 (reported as SF bug [ 737947 ]). + +* The (X)Emacs support is maintained by Alexander Schmolck, so all + comments/requests should be directed to him through the IPython mailing + lists. + +* This code is still somewhat experimental so it's a bit rough around the + edges (although in practice, it works quite well). + +* Be aware that if you customized ``py-python-command`` previously, this value + will override what :file:`ipython.el` does (because loading the customization + variables comes later). + +.. [Emacs] Emacs. http://www.gnu.org/software/emacs/ +.. [TextMate] TextMate: the missing editor. http://macromates.com/ +.. [vim] vim. http://www.vim.org/ diff --git a/docs/source/config/index.txt b/docs/source/config/index.txt index c6b3e87..24f3d82 100644 --- a/docs/source/config/index.txt +++ b/docs/source/config/index.txt @@ -5,7 +5,7 @@ Configuration and customization .. toctree:: :maxdepth: 2 - initial_config.txt - customization.txt - new_config.txt - + overview.txt + ipython.txt + editors.txt + old.txt diff --git a/docs/source/config/ipython.txt b/docs/source/config/ipython.txt new file mode 100644 index 0000000..cf0a670 --- /dev/null +++ b/docs/source/config/ipython.txt @@ -0,0 +1,134 @@ +.. _configuring_ipython: + +=========================================================== +Configuring the :command:`ipython` command line application +=========================================================== + +This section contains information about how to configure the +:command:`ipython` command line application. See the :ref:`configuration +overview ` for a more general description of the +configuration system and configuration file format. + +The default configuration file for the :command:`ipython` command line application +is :file:`ipython_config.py`. By setting the attributes in this file, you +can configure the application. A sample is provided in +:mod:`IPython.config.default.ipython_config`. Simply copy this file to your +IPython directory to start using it. + +Most configuration attributes that this file accepts are associated with +classes that are subclasses of :class:`~IPython.core.component.Component`. + +A few configuration attributes are not associated with a particular +:class:`~IPython.core.component.Component` subclass. These are application +wide configuration attributes and are stored in the ``Global`` +sub-configuration section. We begin with a description of these +attributes. + +Global configuration +==================== + +Assuming that your configuration file has the following at the top:: + + c = get_config() + +the following attributes can be set in the ``Global`` section. + +:attr:`c.Global.display_banner` + A boolean that determined if the banner is printer when :command:`ipython` + is started. + +:attr:`c.Global.classic` + A boolean that determines if IPython starts in "classic" mode. In this + mode, the prompts and everything mimic that of the normal :command:`python` + shell + +:attr:`c.Global.nosep` + A boolean that determines if there should be no blank lines between + prompts. + +:attr:`c.Global.log_level` + An integer that sets the detail of the logging level during the startup + of :command:`ipython`. The default is 30 and the possible values are + (0, 10, 20, 30, 40, 50). Higher is quieter and lower is more verbose. + +:attr:`c.Global.extensions` + A list of strings, each of which is an importable IPython extension. An + IPython extension is a regular Python module or package that has a + :func:`load_in_ipython(ip)` method. This method gets called when the + extension is loaded with the currently running + :class:`~IPython.core.iplib.InteractiveShell` as its only argument. You + can put your extensions anywhere they can be imported but we add the + :file:`extensions` subdirectory of the ipython directory to ``sys.path`` + during extension loading, so you can put them there as well. Extensions + are not executed in the user's interactive namespace and they must + be pure Python code. Extensions are the recommended way of customizing + :command:`ipython`. + +:attr:`c.Global.exec_lines` + A list of strings, each of which is Python code that is run in the user's + namespace after IPython start. These lines can contain full IPython syntax + with magics, etc. + +:attr:`c.Global.exec_files` + A list of strings, each of which is the full pathname of a ``.py`` or + ``.ipy`` file that will be executed as IPython starts. These files are run + in IPython in the user's namespace. Files with a ``.py`` extension need to + be pure Python. Files with a ``.ipy`` extension can have custom IPython + syntax (magics, etc.). These files need to be in the cwd, the ipythondir + or be absolute paths. + +Classes that can be configured +============================== + +The following classes can also be configured in the configuration file for +:command:`ipython`: + +* :class:`~IPython.core.iplib.InteractiveShell` + +* :class:`~IPython.core.prefilter.PrefilterManager` + +* :class:`~IPython.core.alias.AliasManager` + +To see which attributes of these classes are configurable, please see the +source code for these classes, the class docstrings or the sample +configuration file :mod:`IPython.config.default.ipython_config`. + +Example +======= + +For those who want to get a quick start, here is a sample +:file:`ipython_config.py` that sets some of the common configuration +attributes:: + + # sample ipython_config.py + c = get_config() + + c.Global.display_banner = True + c.Global.log_level = 20 + c.Global.extensions = [ + 'myextension' + ] + c.Global.exec_lines = [ + 'import numpy', + 'import scipy' + ] + c.Global.exec_files = [ + 'mycode.py', + 'fancy.ipy' + ] + c.InteractiveShell.autoindent = True + c.InteractiveShell.colors = 'LightBG' + c.InteractiveShell.confirm_exit = False + c.InteractiveShell.deep_reload = True + c.InteractiveShell.editor = 'nano' + c.InteractiveShell.prompt_in1 = 'In [\#]: ' + c.InteractiveShell.prompt_in2 = ' .\D.: ' + c.InteractiveShell.prompt_out = 'Out[\#]: ' + c.InteractiveShell.prompts_pad_left = True + c.InteractiveShell.xmode = 'Context' + + c.PrefilterManager.multi_line_specials = True + + c.AliasManager.user_aliases = [ + ('la', 'ls -al') + ] \ No newline at end of file diff --git a/docs/source/config/initial_config.txt b/docs/source/config/old.txt similarity index 51% rename from docs/source/config/initial_config.txt rename to docs/source/config/old.txt index df1a1e7..feedfa5 100644 --- a/docs/source/config/initial_config.txt +++ b/docs/source/config/old.txt @@ -1,8 +1,13 @@ .. _initial config: -========================================= -Initial configuration of your environment -========================================= +============================================================= +Outdated configuration information that might still be useful +============================================================= + +.. warning:: + + All of the information in this file is outdated. Until the new + configuration system is better documented, this material is being kept. This section will help you set various things in your environment for your IPython sessions to be as efficient as possible. All of IPython's @@ -21,69 +26,6 @@ can change to suit your taste, you can find more details :ref:`here `. Here we discuss the basic things you will want to make sure things are working properly from the beginning. - -.. _accessing_help: - -Access to the Python help system -================================ - -This is true for Python in general (not just for IPython): you should have an -environment variable called PYTHONDOCS pointing to the directory where your -HTML Python documentation lives. In my system it's -:file:`/usr/share/doc/python-doc/html`, check your local details or ask your -systems administrator. - -This is the directory which holds the HTML version of the Python -manuals. Unfortunately it seems that different Linux distributions -package these files differently, so you may have to look around a bit. -Below I show the contents of this directory on my system for reference:: - - [html]> ls - about.html dist/ icons/ lib/ python2.5.devhelp.gz whatsnew/ - acks.html doc/ index.html mac/ ref/ - api/ ext/ inst/ modindex.html tut/ - -You should really make sure this variable is correctly set so that -Python's pydoc-based help system works. It is a powerful and convenient -system with full access to the Python manuals and all modules accessible -to you. - -Under Windows it seems that pydoc finds the documentation automatically, -so no extra setup appears necessary. - - -Editor -====== - -The %edit command (and its alias %ed) will invoke the editor set in your -environment as EDITOR. If this variable is not set, it will default to -vi under Linux/Unix and to notepad under Windows. You may want to set -this variable properly and to a lightweight editor which doesn't take -too long to start (that is, something other than a new instance of -Emacs). This way you can edit multi-line code quickly and with the power -of a real editor right inside IPython. - -If you are a dedicated Emacs user, you should set up the Emacs server so -that new requests are handled by the original process. This means that -almost no time is spent in handling the request (assuming an Emacs -process is already running). For this to work, you need to set your -EDITOR environment variable to 'emacsclient'. The code below, supplied -by Francois Pinard, can then be used in your .emacs file to enable the -server:: - - (defvar server-buffer-clients) - (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) - (server-start) - (defun fp-kill-server-with-buffer-routine () - (and server-buffer-clients (server-done))) - (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) - -You can also set the value of this editor via the commmand-line option -'-editor' or in your ipythonrc file. This is useful if you wish to use -specifically for IPython an editor different from your typical default -(and for Windows users who tend to use fewer environment variables). - - Color ===== @@ -133,7 +75,6 @@ IPython uses colors for two main groups of things: prompts and tracebacks which are directly printed to the terminal, and the object introspection system which passes large sets of data through a pager. - Input/Output prompts and exception tracebacks ============================================= @@ -191,60 +132,99 @@ documentation for details. If you are on a system which lacks proper data pagers (such as Windows), IPython will use a very limited builtin pager. -.. _emacs: - -(X)Emacs configuration -====================== - -Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, -currently (X)Emacs and IPython get along very well. - -Important note: You will need to use a recent enough version of -python-mode.el, along with the file ipython.el. You can check that the -version you have of python-mode.el is new enough by either looking at -the revision number in the file itself, or asking for it in (X)Emacs via -M-x py-version. Versions 4.68 and newer contain the necessary fixes for -proper IPython support. - -The file ipython.el is included with the IPython distribution, in the -documentation directory (where this manual resides in PDF and HTML -formats). - -Once you put these files in your Emacs path, all you need in your .emacs -file is:: - - (require 'ipython) - -This should give you full support for executing code snippets via -IPython, opening IPython as your Python shell via ``C-c !``, etc. - -You can customize the arguments passed to the IPython instance at startup by -setting the ``py-python-command-args`` variable. For example, to start always -in ``pylab`` mode with hardcoded light-background colors, you can use:: - - (setq py-python-command-args '("-pylab" "-colors" "LightBG")) - -If you happen to get garbage instead of colored prompts as described in -the previous section, you may need to set also in your .emacs file:: - - (setq ansi-color-for-comint-mode t) - -Notes: +.. _Prompts: + +Fine-tuning your prompt +======================= + +IPython's prompts can be customized using a syntax similar to that of +the bash shell. Many of bash's escapes are supported, as well as a few +additional ones. We list them below:: + + \# + the prompt/history count number. This escape is automatically + wrapped in the coloring codes for the currently active color scheme. + \N + the 'naked' prompt/history count number: this is just the number + itself, without any coloring applied to it. This lets you produce + numbered prompts with your own colors. + \D + the prompt/history count, with the actual digits replaced by dots. + Used mainly in continuation prompts (prompt_in2) + \w + the current working directory + \W + the basename of current working directory + \Xn + where $n=0\ldots5.$ The current working directory, with $HOME + replaced by ~, and filtered out to contain only $n$ path elements + \Yn + Similar to \Xn, but with the $n+1$ element included if it is ~ (this + is similar to the behavior of the %cn escapes in tcsh) + \u + the username of the current user + \$ + if the effective UID is 0, a #, otherwise a $ + \h + the hostname up to the first '.' + \H + the hostname + \n + a newline + \r + a carriage return + \v + IPython version string + +In addition to these, ANSI color escapes can be insterted into the +prompts, as \C_ColorName. The list of valid color names is: Black, Blue, +Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, +LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White, +Yellow. + +Finally, IPython supports the evaluation of arbitrary expressions in +your prompt string. The prompt strings are evaluated through the syntax +of PEP 215, but basically you can use $x.y to expand the value of x.y, +and for more complicated expressions you can use braces: ${foo()+x} will +call function foo and add to it the value of x, before putting the +result into your prompt. For example, using +prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' +will print the result of the uptime command on each prompt (assuming the +commands module has been imported in your ipythonrc file). + + + Prompt examples + +The following options in an ipythonrc file will give you IPython's +default prompts:: + + prompt_in1 'In [\#]:' + prompt_in2 ' .\D.:' + prompt_out 'Out[\#]:' + +which look like this:: + + In [1]: 1+2 + Out[1]: 3 + + In [2]: for i in (1,2,3): + ...: print i, + ...: + 1 2 3 + +These will give you a very colorful prompt with path information:: + + #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' + prompt_in2 ' ..\D>' + prompt_out '<\#>' + +which look like this:: + + fperez[~/ipython]1> 1+2 + <1> 3 + fperez[~/ipython]2> for i in (1,2,3): + ...> print i, + ...> + 1 2 3 - * There is one caveat you should be aware of: you must start the - IPython shell before attempting to execute any code regions via - ``C-c |``. Simply type C-c ! to start IPython before passing any code - regions to the interpreter, and you shouldn't experience any - problems. - This is due to a bug in Python itself, which has been fixed for - Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [ - 737947 ]). - * The (X)Emacs support is maintained by Alexander Schmolck, so all - comments/requests should be directed to him through the IPython - mailing lists. - * This code is still somewhat experimental so it's a bit rough - around the edges (although in practice, it works quite well). - * Be aware that if you customize py-python-command previously, this - value will override what ipython.el does (because loading the - customization variables comes later). diff --git a/docs/source/config/overview.txt b/docs/source/config/overview.txt new file mode 100644 index 0000000..b6ffc21 --- /dev/null +++ b/docs/source/config/overview.txt @@ -0,0 +1,331 @@ +.. _config_overview: + +============================================ +Overview of the IPython configuration system +============================================ + +This section describes the IPython configuration system. Starting with version +0.11, IPython has a completely new configuration system that is quite +different from the older :file:`ipythonrc` or :file:`ipy_user_conf.py` +approaches. The new configuration system was designed from scratch to address +the particular configuration needs of IPython. While there are many +other excellent configuration systems out there, we found that none of them +met our requirements. + +.. warning:: + + If you are upgrading to version 0.11 of IPython, you will need to migrate + your old :file:`ipythonrc` or :file:`ipy_user_conf.py` configuration files + to the new system. Read on for information on how to do this. + +The discussion that follows is focused on teaching user's how to configure +IPython to their liking. Developer's who want to know more about how they +can enable their objects to take advantage of the configuration system +should consult our :ref:`developer guide ` + +The main concepts +================= + +There are a number of abstractions that the IPython configuration system uses. +Each of these abstractions is represented by a Python class. + +Configuration object: :class:`~IPython.config.loader.Config` + A configuration object is a simple dictionary-like class that holds + configuration attributes and sub-configuration objects. These classes + support dotted attribute style access (``Foo.bar``) in addition to the + regular dictionary style access (``Foo['bar']``). Configuration objects + are smart. They know how to merge themselves with other configuration + objects and they automatically create sub-configuration objects. + +Application: :class:`~IPython.core.application.Application` + An application is a process that does a specific job. The most obvious + application is the :command:`ipython` command line program. Each + application reads a *single* configuration file and command line options + and then produces a master configuration object for the application. This + configuration object is then passed to the components that the application + creates. Components implement the actual logic of the application and know + how to configure themselves given the configuration object. + +Component: :class:`~IPython.core.component.Component` + A component is a regular Python class that serves as a base class for all + main classes in an application. The + :class:`~IPython.core.component.Component` base class is lightweight and + only does two main things. + + First, it keeps track of all instances of itself and provides an + interfaces for querying those instances. This enables components to get + references to other components, even though they are not "nearby" in the + runtime object graph. + + Second, it declares what class attributes are configurable and specifies + the default types and values of those attributes. This information is used + to automatically configure instances given the applications configuration + object. + + Developers create :class:`~IPython.core.component.Component` subclasses + that implement all of the logic in the application. Each of these + subclasses has its own configuration information that controls how + instances are created. + +Having described these main concepts, we can now state the main idea in our +configuration system: *"configuration" allows the default values of class +attributes to be controlled on a class by class basis*. Thus all instances of +a given class are configured in the same way. Furthermore, if two instances +need to be configured differently, they need to be instances of two different +classes. While this model may seem a bit restrictive, we have found that it +expresses most things that need to be configured extremely well. + +Now, we show what our configuration objects and files look like. + +Configuration objects and files +=============================== + +A configuration file is simply a pure Python file that sets the attributes +of a global, pre-created configuration object. This configuration object is a +:class:`~IPython.config.loader.Config` instance. While in a configuration +file, to get a reference to this object, simply call the :func:`get_config` +function. We inject this function into the global namespace that the +configuration file is executed in. + +Here is an example of a super simple configuration file that does nothing:: + + c = get_config() + +Once you get a reference to the configuration object, you simply set +attributes on it. All you have to know is: + +* The name of each attribute. +* The type of each attribute. + +The answers to these two questions are provided by the various +:class:`~IPython.core.component.Component` subclasses that an application +uses. Let's look at how this would work for a simple component subclass:: + + # Sample component that can be configured. + from IPython.core.component import Component + from IPython.utils.traitlets import Int, Float, Str, Bool + + class MyComponent(Component): + name = Str('defaultname', config=True) + ranking = Int(0, config=True) + value = Float(99.0) + # The rest of the class implementation would go here.. + +In this example, we see that :class:`MyComponent` has three attributes, two +of whom (``name``, ``ranking``) can be configured. All of the attributes +are given types and default values. If a :class:`MyComponent` is instantiated, +but not configured, these default values will be used. But let's see how +to configure this class in a configuration file:: + + # Sample config file + c = get_config() + + c.MyComponent.name = 'coolname' + c.MyComponent.ranking = 10 + +After this configuration file is loaded, the values set in it will override +the class defaults anytime a :class:`MyComponent` is created. Furthermore, +these attributes will be type checked and validated anytime they are set. +This type checking is handled by the :mod:`IPython.utils.traitlets` module, +which provides the :class:`Str`, :class:`Int` and :class:`Float` types. In +addition to these traitlets, the :mod:`IPython.utils.traitlets` provides +traitlets for a number of other types. + +.. note:: + + Underneath the hood, the :class:`Component` base class is a subclass of + :class:`IPython.utils.traitlets.HasTraitlets`. The + :mod:`IPython.utils.traitlets` module is a lightweight version of + :mod:`enthought.traits`. Our implementation is a pure Python subset + (mostly API compatible) of :mod:`enthought.traits` that does not have any + of the automatic GUI generation capabilities. Our plan is to achieve 100% + API compatibility to enable the actual :mod:`enthought.traits` to + eventually be used instead. Currently, we cannot use + :mod:`enthought.traits` as we are committed to the core of IPython being + pure Python. + +It should be very clear at this point what the naming convention is for +configuration attributes:: + + c.ClassName.attribute_name = attribute_value + +Here, ``ClassName`` is the name of the class whose configuration attribute you +want to set, ``attribute_name`` is the name of the attribute you want to set +and ``attribute_value`` the the value you want it to have. The ``ClassName`` +attribute of ``c`` is not the actual class, but instead is another +:class:`~IPython.config.loader.Config` instance. + +.. note:: + + The careful reader may wonder how the ``ClassName`` (``MyComponent`` in + the above example) attribute of the configuration object ``c`` gets + created. These attributes are created on the fly by the + :class:`~IPython.config.loader.Config` instance, using a simple naming + convention. Any attribute of a :class:`~IPython.config.loader.Config` + instance whose name begins with an uppercase character is assumed to be a + sub-configuration and a new empty :class:`~IPython.config.loader.Config` + instance is dynamically created for that attribute. This allows deeply + hierarchical information created easily (``c.Foo.Bar.value``) on the + fly. + +Configuration files inheritance +=============================== + +Let's say you want to have different configuration files for various purposes. +Our configuration system makes it easy for one configuration file to inherit +the information in another configuration file. The :func:`load_subconfig` +command can be used in a configuration file for this purpose. Here is a simple +example that loads all of the values from the file :file:`base_config.py`:: + + # base_config.py + c = get_config() + c.MyComponent.name = 'coolname' + c.MyComponent.ranking = 100 + +into the configuration file :file:`main_config.py`:: + + # main_config.py + c = get_config() + + # Load everything from base_config.py + load_subconfig('base_config.py') + + # Now override one of the values + c.MyComponent.name = 'bettername' + +In a situation like this the :func:`load_subconfig` makes sure that the +search path for sub-configuration files is inherited from that of the parent. +Thus, you can typically put the two in the same directory and everything will +just work. + +Class based configuration inheritance +===================================== + +There is another aspect of configuration where inheritance comes into play. +Sometimes, your classes will have an inheritance hierarchy that you want +to be reflected in the configuration system. Here is a simple example:: + + from IPython.core.component import Component + from IPython.utils.traitlets import Int, Float, Str, Bool + + class Foo(Component): + name = Str('fooname', config=True) + value = Float(100.0, config=True) + + class Bar(Foo): + name = Str('barname', config=True) + othervalue = Int(0, config=True) + +Now, we can create a configuration file to configure instances of :class:`Foo` +and :class:`Bar`:: + + # config file + c = get_config() + + c.Foo.name = 'bestname' + c.Bar.othervalue = 10 + +This class hierarchy and configuration file accomplishes the following: + +* The default value for :attr:`Foo.name` and :attr:`Bar.name` will be + 'bestname'. Because :class:`Bar` is a :class:`Foo` subclass it also + picks up the configuration information for :class:`Foo`. +* The default value for :attr:`Foo.value` and :attr:`Bar.value` will be + ``100.0``, which is the value specified as the class default. +* The default value for :attr:`Bar.othervalue` will be 10 as set in the + configuration file. Because :class:`Foo` is the parent of :class:`Bar` + it doesn't know anything about the :attr:`othervalue` attribute. + +Configuration file location +=========================== + +So where should you put your configuration files? By default, all IPython +applications look in the so called "IPython directory". The location of +this directory is determined by the following algorithm: + +* If the ``-ipythondir`` command line flag is given, its value is used. + +* If not, the value returned by :func:`IPython.utils.genutils.get_ipython_dir` + is used. This function will first look at the :envvar:`IPYTHONDIR` + environment variable and then default to the directory + :file:`$HOME/.ipythondir`. + +For most users, the default value will simply be something like +:file:`$HOME/.ipythondir`. + +Once the location of the IPython directory has been determined, you need to +know what filename to use for the configuration file. The basic idea is that +each application has its own default configuration filename. The default named +used by the :command:`ipython` command line program is +:file:`ipython_config.py`. This value can be overriden by the ``-config_file`` +command line flag. A sample :file:`ipython_config.py` file can be found +in :mod:`IPython.config.default.ipython_config.py`. Simple copy it to your +IPython directory to begin using it. + +.. _Profiles: + +Profiles +======== + +A profile is simply a configuration file that follows a simple naming +convention and can be loaded using a simplified syntax. The idea is +that users often want to maintain a set of configuration files for different +purposes: one for doing numerical computing with NumPy and SciPy and +another for doing symbolic computing with SymPy. Profiles make it easy +to keep a separate configuration file for each of these purposes. + +Let's start by showing how a profile is used: + +.. code-block:: bash + + $ ipython -p sympy + +This tells the :command:`ipython` command line program to get its +configuration from the "sympy" profile. The search path for profiles is the +same as that of regular configuration files. The only difference is that +profiles are named in a special way. In the case above, the "sympy" profile +would need to have the name :file:`ipython_config_sympy.py`. + +The general pattern is this: simply add ``_profilename`` to the end of the +normal configuration file name. Then load the profile by adding ``-p +profilename`` to your command line options. + +IPython ships with some sample profiles in :mod:`IPython.config.profile`. +Simply copy these to your IPython directory to begin using them. + +Design requirements +=================== + +Here are the main requirements we wanted our configuration system to have: + +* Support for hierarchical configuration information. + +* Full integration with command line option parsers. Often, you want to read + a configuration file, but then override some of the values with command line + options. Our configuration system automates this process and allows each + command line option to be linked to a particular attribute in the + configuration hierarchy that it will override. + +* Configuration files that are themselves valid Python code. This accomplishes + many things. First, it becomes possible to put logic in your configuration + files that sets attributes based on your operating system, network setup, + Python version, etc. Second, Python has a super simple syntax for accessing + hierarchical data structures, namely regular attribute access + (``Foo.Bar.Bam.name``). Third, using Python makes it easy for users to + import configuration attributes from one configuration file to another. + Forth, even though Python is dynamically typed, it does have types that can + be checked at runtime. Thus, a ``1`` in a config file is the integer '1', + while a ``'1'`` is a string. + +* A fully automated method for getting the configuration information to the + classes that need it at runtime. Writing code that walks a configuration + hierarchy to extract a particular attribute is painful. When you have + complex configuration information with hundreds of attributes, this makes + you want to cry. + +* Type checking and validation that doesn't require the entire configuration + hierarchy to be specified statically before runtime. Python is a very + dynamic language and you don't always know everything that needs to be + configured when a program starts. + + diff --git a/docs/source/development/coding_guide.txt b/docs/source/development/coding_guide.txt index ec7ff28..a6155cd 100644 --- a/docs/source/development/coding_guide.txt +++ b/docs/source/development/coding_guide.txt @@ -1,39 +1,36 @@ -============== - Coding guide -============== +============ +Coding guide +============ - -Coding conventions -================== +General coding conventions +========================== In general, we'll try to follow the standard Python style conventions as -described in Python's `PEP 8`_, the official Python Style Guide. +described in Python's PEP 8 [PEP8]_, the official Python Style Guide. -.. _PEP 8: http://www.python.org/peps/pep-0008.html +Other general comments: -Other comments: - -- In a large file, top level classes and functions should be separated by 2-3 +* In a large file, top level classes and functions should be separated by 2 lines to make it easier to separate them visually. -- Use 4 spaces for indentation, *never* use hard tabs. +* Use 4 spaces for indentation, **never** use hard tabs. -- Keep the ordering of methods the same in classes that have the same methods. +* Keep the ordering of methods the same in classes that have the same methods. This is particularly true for classes that implement similar interfaces and for interfaces that are similar. Naming conventions ------------------- +================== -In terms of naming conventions, we'll follow the guidelines of PEP 8. Some of -the existing code doesn't honor this perfectly, but for all new IPython code -(and much existing code is being refactored), we'll use: +In terms of naming conventions, we'll follow the guidelines of PEP 8 [PEP8]_. +Some of the existing code doesn't honor this perfectly, but for all new +IPython code (and much existing code is being refactored), we'll use: -- All ``lowercase`` module names. +* All ``lowercase`` module names. -- ``CamelCase`` for class names. +* ``CamelCase`` for class names. -- ``lowercase_with_underscores`` for methods, functions, variables and +* ``lowercase_with_underscores`` for methods, functions, variables and attributes. This may be confusing as some of the existing codebase uses a different @@ -48,80 +45,6 @@ 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. - -Older material -============== - -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 @@ -134,7 +57,7 @@ cases like this, we propose the following policy: sparingly! Implementation-specific *private* methods will use -``_single_underscore_prefix``. Names with a leading double underscore will +``_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). @@ -148,9 +71,8 @@ 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 +something else. However, if a prefix seems absolutely necessary the more specific ``IPY`` or ``ipy`` are preferred. +.. [PEP8] Python Enhancement Proposal 8. http://www.python.org/peps/pep-0008.html diff --git a/docs/source/development/contributing.txt b/docs/source/development/contributing.txt index 6a11f72..ab57554 100644 --- a/docs/source/development/contributing.txt +++ b/docs/source/development/contributing.txt @@ -1,30 +1,38 @@ +.. _contributing: + +============================ How to contribute to IPython ============================ +Overview +======== + 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:: +If you have a small change that you want to contribute, you can edit your +Bazaar checkout of IPython (see below) in-place, and ask Bazaar for the +differences: + +.. code-block:: bash $ 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 +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, +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 +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 +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 @@ -32,7 +40,9 @@ 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:: +you, try the following: + +.. code-block:: bash $ bzr whoami Joe Coder @@ -46,7 +56,9 @@ Get the main IPython branch from Launchpad ------------------------------------------ Now, you can get a copy of the main IPython development branch (we call this -the "trunk"):: +the "trunk"): + +.. code-block:: bash $ bzr branch lp:ipython @@ -56,7 +68,9 @@ 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:: +"ipython-mybranch". Create this branch by doing: + +.. code-block:: bash $ bzr branch ipython ipython-mybranch @@ -70,7 +84,9 @@ 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:: +installed. Then, just do: + +.. code-block:: bash $ cd ipython-mybranch $ python setupegg.py develop @@ -78,7 +94,9 @@ installed. Then, just do:: 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:: +this: + +.. code-block:: bash $ ...do work in ipython-mybranch... $ bzr commit -m "the commit message goes here" @@ -98,7 +116,9 @@ approach in the commit messages (including the second line being left 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:: +commands: + +.. code-block:: bash $ ls ipython @@ -110,82 +130,80 @@ commands:: $ 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:: +do: + +.. code-block:: bash $ 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? +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. +* All code is documented. How to document your code is described in + :ref:`this section `. +* All code has tests. How to write and run tests is described in + :ref:`this section `. * The entire IPython test suite passes. +You should also provide us with a list of changes that your branch contains. +See the :ref:`What's new ` section of our documentation +(:file:`docs/source/whatsnew`) for details on the format and content of this. + 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 -===================================================================== +Merging a branch into trunk +=========================== 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 +main Launchpad site. There are a number of things to keep in mind when doing +this, 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 +* When you merge any non-trivial functionality (from one small bug fix to a + big feature branch), please remember to always edit the appropriate file in + the :ref:`What's new ` section of our documentation. + Ideally, the author of the branch should provide this content when they + submit the branch for review. But if they don't it is the responsibility of + the developer doing the merge to add this information. + +* When merges are done, the practice of putting a summary commit message in + the merge is *extremely* useful. It is probably easiest if you simply use + the same list of changes that were added to the :ref:`What's new + ` section of the documentation. + +* 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 + touch the code too much. + + +.. [Bazaar] Bazaar. http://bazaar-vcs.org/ +.. [Launchpad] Launchpad. http://www.launchpad.net/ipython diff --git a/docs/source/development/doc_guide.txt b/docs/source/development/doc_guide.txt index f23d826..8f728ce 100644 --- a/docs/source/development/doc_guide.txt +++ b/docs/source/development/doc_guide.txt @@ -8,31 +8,30 @@ Standalone documentation ======================== All standalone documentation should be written in plain text (``.txt``) files -using `reStructuredText`_ for markup and formatting. All such documentation -should be placed in the top level directory ``docs`` of the IPython source -tree. Or, when appropriate, a suitably named subdirectory should be used. The -documentation in this location will serve as the main source for IPython -documentation and all existing documentation should be converted to this -format. - -The actual HTML and PDF docs are built using the Sphinx_ documentation -generation tool. Sphinx has been adopted as the default documentation tool for -Python itself as of version 2.6, as well as by a number of projects that -IPython is related with, such as numpy, scipy, matplotlib, sage and nipy. +using reStructuredText [reStructuredText]_ for markup and formatting. All such +documentation should be placed in the directory :file:`docs/source` of the +IPython source tree. Or, when appropriate, a suitably named subdirectory +should be used. The documentation in this location will serve as the main +source for IPython documentation. -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Sphinx: http://sphinx.pocoo.org/ +The actual HTML and PDF docs are built using the Sphinx [Sphinx]_ +documentation generation tool. Once you have Sphinx installed, you can build +the html docs yourself by doing: +.. code-block:: bash -The rest of this document is mostly taken from the `matploblib -documentation`__; we are using a number of Sphinx tools and extensions written -by the matplotlib team and will mostly follow their conventions, which are -nicely spelled out in their guide. What follows is thus a lightly adapted -version of the matplotlib documentation guide, taken with permission from the -MPL team. + $ cd ipython-mybranch/docs + $ make html -.. __: http://matplotlib.sourceforge.net/devel/documenting_mpl.html +Our usage of Sphinx follows that of matplotlib [Matplotlib]_ closely. We are +using a number of Sphinx tools and extensions written by the matplotlib team +and will mostly follow their conventions, which are nicely spelled out in +their documentation guide [MatplotlibDocGuide]_. What follows is thus a +abridged version of the matplotlib documentation guide, taken with permission +from the matplotlib team. +If you are reading this in a web browser, you can click on the "Show Source" +link to see the original reStricturedText for the following examples. A bit of Python code:: @@ -46,7 +45,6 @@ An interactive Python session:: >>> genutils.get_ipython_dir() '/home/fperez/.ipython' - An IPython session: .. code-block:: ipython @@ -68,12 +66,11 @@ A bit of shell code: echo "My home directory is: $HOME" ls - Docstring format ================ Good docstrings are very important. Unfortunately, Python itself only provides -a rather loose standard for docstrings (`PEP 257`_), and there is no universally +a rather loose standard for docstrings [PEP257]_, and there is no universally accepted convention for all the different parts of a complete docstring. However, the NumPy project has established a very reasonable standard, and has developed some tools to support the smooth inclusion of such docstrings in @@ -82,60 +79,26 @@ IPython will be henceforth documented using the NumPy conventions; we carry copies of some of the NumPy support tools to remain self-contained, but share back upstream with NumPy any improvements or fixes we may make to the tools. -The `NumPy documentation guidelines`_ contain detailed information on this -standard, and for a quick overview, the NumPy `example docstring`_ is a useful -read. +The NumPy documentation guidelines [NumPyDocGuide]_ contain detailed +information on this standard, and for a quick overview, the NumPy example +docstring [NumPyExampleDocstring]_ is a useful read. -As in the past IPython used epydoc, currently many docstrings still use epydoc -conventions. We will update them as we go, but all new code should be fully +In the past IPython used epydoc so currently many docstrings still use epydoc +conventions. We will update them as we go, but all new code should be documented using the NumPy standard. -.. _PEP 257: http://www.python.org/peps/pep-0257.html -.. _NumPy documentation guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines - -.. _example docstring: http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt - -Additional PEPs of interest regarding documentation of code. While both of -these were rejected, the ideas therein form much of the basis of docutils (the -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 +Here are two additional PEPs of interest regarding documentation of code. +While both of these were rejected, the ideas therein form much of the basis of +docutils (the machinery to process reStructuredText): -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 `_ + +.. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html +.. [Sphinx] Sphinx. http://sphinx.pocoo.org/ +.. [MatplotlibDocGuide] http://matplotlib.sourceforge.net/devel/documenting_mpl.html +.. [PEP257] PEP 257. http://www.python.org/peps/pep-0257.html +.. [NumPyDocGuide] NumPy documentation guide. http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines +.. [NumPyExampleDocstring] NumPy example docstring. http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt + diff --git a/docs/source/development/index.txt b/docs/source/development/index.txt index 010cf96..5b41f8d 100644 --- a/docs/source/development/index.txt +++ b/docs/source/development/index.txt @@ -5,7 +5,7 @@ IPython developer's guide ========================= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 contributing.txt coding_guide.txt @@ -13,13 +13,6 @@ IPython developer's guide testing.txt release.txt roadmap.txt - - notification_blueprint.txt reorg.txt + notification_blueprint.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/overview.txt b/docs/source/development/overview.txt deleted file mode 100644 index 12a6f48..0000000 --- a/docs/source/development/overview.txt +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - diff --git a/docs/source/development/release.txt b/docs/source/development/release.txt index a7d7d08..f857624 100644 --- a/docs/source/development/release.txt +++ b/docs/source/development/release.txt @@ -1,6 +1,12 @@ -Release checklist +.. _releasing_ipython: + +================= +Releasing IPython ================= +This section contains notes about the process that is used to release IPython. +Our release process is currently not very formal and could be improved. + 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. @@ -13,12 +19,13 @@ Most of the release process is automated by the :file:`release` script in the #. 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. +#. Update 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. + the html version of the :ref:`Whats new ` section of the + documentation. #. Make sure that the released version of the docs is live on the site. diff --git a/docs/source/development/reorg.txt b/docs/source/development/reorg.txt index 8db81eb..00a2375 100644 --- a/docs/source/development/reorg.txt +++ b/docs/source/development/reorg.txt @@ -1,85 +1,64 @@ -============================= -IPython module reorganization -============================= +.. _module_reorg: -Currently, IPython has many top-level modules that serve many different -purposes. The lack of organization make it very difficult for developers to -work on IPython and understand its design. This document contains notes about -how we will reorganize the modules into sub-packages. +=========================== +IPython module organization +=========================== -.. warning:: +As of the 0.11 release of IPython, the top-level packages and modules have +been completely reorganized. This section describes the purpose of the +top-level IPython subpackages. - This effort will possibly break third party packages that use IPython as - a library or hack on the IPython internals. +Subpackage descriptions +======================= -.. warning:: +* :mod:`IPython.config`. This package contains the configuration system of + IPython, as well as default configuration files for the different IPython + applications. - This effort will result in the removal from IPython of certain modules - that are not used anymore, don't currently work, are unmaintained, etc. - - -Current subpackges -================== - -IPython currently has the following sub-packages: - -* :mod:`IPython.config` - -* :mod:`IPython.Extensions` - -* :mod:`IPython.external` - -* :mod:`IPython.frontend` - -* :mod:`IPython.gui` +* :mod:`IPython.core`. This sub-package contains the core of the IPython + interpreter, but none of its extended capabilities. -* :mod:`IPython.kernel` +* :mod:`IPython.deathrow`. This is for code that is outdated, untested, + rotting, or that belongs in a separate third party project. Eventually all + this code will either i) be revived by someone willing to maintain it with + tests and docs and re-included into IPython or 2) be removed from IPython + proper, but put into a separate third-party Python package. No new code will + be allowed here. -* :mod:`IPython.testing` +* :mod:`IPython.extensions`. This package contains fully supported IPython + extensions. These extensions adhere to the official IPython extension API + and can be enabled by adding them to a field in the configuration file. -* :mod:`IPython.tests` +* :mod:`IPython.external`. This package contains third party packages and + modules that IPython ships internally to reduce the number of dependencies. + Usually, these are short, single file modules. -* :mod:`IPython.tools` +* :mod:`IPython.frontend`. This package contains the various IPython + frontends. Currently, the code in this subpackage is very experimental and + may be broken. -* :mod:`IPython.UserConfig` +* :mod:`IPython.gui`. Another semi-experimental wxPython based IPython GUI. -New Subpackages to be created -============================= +* :mod:`IPython.kernel`. This contains IPython's parallel computing system. -We propose to create the following new sub-packages: +* :mod:`IPython.lib`. IPython has many extended capabilities that are not part + of the IPython core. These things will go here and in. Modules in this + package are similar to extensions, but don't adhere to the official + IPython extension API. -* :mod:`IPython.core`. This sub-package will contain the core of the IPython - interpreter, but none of its extended capabilities. +* :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's + standards, but that we plan on keeping. To be moved out of this sub-package + a module needs to have approval of the core IPython developers, tests and + documentation. -* :mod:`IPython.lib`. IPython has many extended capabilities that are not part - of the IPython core. These things will go here. +* :mod:`IPython.scripts`. This package contains a variety of top-level + command line scripts. Eventually, these should be moved to the + :file:`scripts` subdirectory of the appropriate IPython subpackage. * :mod:`IPython.utils`. This sub-package will contain anything that might eventually be found in the Python standard library, like things in :mod:`genutils`. Each sub-module in this sub-package should contain - functions and classes that serve a single purpose. - -* :mod:`IPython.deathrow`. This is for code that is untested and/or rotting - and needs to be removed from IPython. Eventually all this code will either - i) be revived by someone willing to maintain it with tests and docs and - re-included into IPython or 2) be removed from IPython proper, but put into - a separate top-level (not IPython) package that we keep around. No new code - will be allowed here. - -* :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's - standards, but that we plan on keeping. To be moved out of this sub-package - a module needs to have a maintainer, tests and documentation. - -Procedure -========= - -1. Move the file to its new location with its new name. -2. Rename all import statements to reflect the change. -3. Run PyFlakes on each changes module. -4. Add tests/test_imports.py to test it. - -Status -====== + functions and classes that serve a single purpose and that don't + depend on things in the rest of IPython. -This branch was merged into trunk in early August of 2009. diff --git a/docs/source/development/roadmap.txt b/docs/source/development/roadmap.txt index a59c7aa..d7912ce 100644 --- a/docs/source/development/roadmap.txt +++ b/docs/source/development/roadmap.txt @@ -42,26 +42,26 @@ Major areas of work Refactoring the main IPython core --------------------------------- -During the summer of 2009, we began refactoring IPython's core. The main -thrust in this work was make the IPython core into a set of loosely coupled -components. The base component class for this is -:class:`IPython.core.component.Component`. This section outlines the status -of this work. +During the summer of 2009, we began refactoring IPython's core. The main +thrust in this work was to make the IPython core into a set of loosely coupled +components. The base component class for this is +:class:`IPython.core.component.Component`. This section outlines the status of +this work. Parts of the IPython core that have been turned into components: -* The main :class:`InteractiveShell` class. -* The aliases (:mod:`IPython.core.aliases`). +* The main :class:`~IPython.core.iplib.InteractiveShell` class. +* The aliases (:mod:`IPython.core.alias`). * The display and builtin traps (:mod:`IPython.core.display_trap` and :mod:`IPython.core.builtin_trap`). * The prefilter machinery (:mod:`IPython.core.prefilter`). -Parts of the IPythoncore that need to be turned into components: +Parts of the IPythoncore that still need to be turned into components: * Magics. * Input and output history management. * Prompts. -* Completers. +* Tab completers. * Logging. * Exception handling. * Anything else. @@ -69,6 +69,13 @@ Parts of the IPythoncore that need to be turned into components: Process management for :mod:`IPython.kernel` -------------------------------------------- +A number of things need to be done to improve how processes are started +up and managed for the parallel computing side of IPython: + +* All of the processes need to use the new configuration system, components + and application. +* We need to add support for other batch systems. + Performance problems -------------------- @@ -103,9 +110,9 @@ 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. + 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 diff --git a/docs/source/development/testing.txt b/docs/source/development/testing.txt index 436b2de..1a5971f 100644 --- a/docs/source/development/testing.txt +++ b/docs/source/development/testing.txt @@ -28,13 +28,14 @@ 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: +* To run regular tests, use the :command:`nosetests` command that Nose [Nose]_ + provides 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 +* To run Twisted-using tests, use the :command:`trial` command on a per file basis: .. code-block:: bash @@ -45,150 +46,9 @@ we recommend the following testing practices: 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. + ``TestCase`` class that comes with ``twisted.trial.unittest``. Furthermore, + 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. +.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/ diff --git a/docs/source/install/install.txt b/docs/source/install/install.txt index e005a50..20187d0 100644 --- a/docs/source/install/install.txt +++ b/docs/source/install/install.txt @@ -38,16 +38,23 @@ optional dependencies: .. code-block:: bash - easy_install ipython[kernel,security,test] + $ 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: +enable you to run IPython's test suite. + +.. warning:: + + IPython's test system is being refactored and currently the + :command:`iptest` shown below does not work. More details about the + testing situation can be found :ref:`here ` + +To run IPython's test suite, use the :command:`iptest` command: .. code-block:: bash - iptest + $ iptest Read on for more specific details and instructions for Windows. @@ -70,7 +77,7 @@ to simple use :command:`easy_install`: .. code-block:: bash - easy_install ipython + $ easy_install ipython That's it. @@ -83,9 +90,9 @@ just grab the latest stable build of IPython from `here .. 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`. @@ -125,9 +132,9 @@ need to have Bazaar installed on your system. Then just do: .. code-block:: bash - bzr branch lp:ipython - cd ipython - python setup.py install + $ 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. @@ -138,7 +145,7 @@ 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, @@ -146,7 +153,7 @@ just do: .. code-block:: bash - bzr pull + $ bzr pull Basic optional dependencies =========================== @@ -183,9 +190,9 @@ working :mod:`readline` module, just do (with :mod:`setuptools` installed): .. code-block:: bash - easy_install readline + $ easy_install readline -.. note: +.. note:: Other Python distributions on OS X (such as fink, MacPorts and the official python.org binaries) already have readline installed so @@ -210,21 +217,27 @@ 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: .. code-block:: bash - easy_install ipython[test] + $ 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: +`_. + +.. warning:: + + As described above, the :command:`iptest` command currently doesn't work. + +Once you have nose installed, you can run IPython's test suite using the +iptest command: .. code-block:: bash - iptest + $ iptest pexpect ------- @@ -234,7 +247,7 @@ The `pexpect `_ package is used in IPython's .. code-block:: bash - easy_install pexpect + $ easy_install pexpect Windows users are out of luck as pexpect does not run there. @@ -255,8 +268,8 @@ On a Unix style platform (including OS X), if you want to use .. code-block:: bash - easy_install ipython[kernel] # the first three - easy_install ipython[security] # pyOpenSSL + $ easy_install ipython[kernel] # the first three + $ easy_install ipython[security] # pyOpenSSL zope.interface and Twisted -------------------------- @@ -267,13 +280,13 @@ 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 -[Twisted]_ and the `zope.interface page at PyPI -`_ and do the usual ``python -setup.py install`` if you prefer. +[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 @@ -288,7 +301,7 @@ 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``