diff --git a/docs/autogen_api.py b/docs/autogen_api.py index 82fa29b..8885b66 100755 --- a/docs/autogen_api.py +++ b/docs/autogen_api.py @@ -15,19 +15,25 @@ if __name__ == '__main__': package = 'IPython' outdir = pjoin('source','api','generated') docwriter = ApiDocWriter(package,rst_extension='.txt') + # You have to escape the . here because . is a special char for regexps. + # You must do make clean if you change this! docwriter.package_skip_patterns += [r'\.fixes$', - r'\.externals$', + r'\.external$', r'\.extensions', - r'\.kernel.config', + r'\.kernel\.config', r'\.attic', r'\.quarantine', - r'\.deathrow' + r'\.deathrow', + r'\.config\.default', + r'\.config\.profile', + r'\.frontend', + r'\.gui' ] - docwriter.module_skip_patterns += [ r'\.core.fakemodule', + docwriter.module_skip_patterns += [ r'\.core\.fakemodule', r'\.cocoa', r'\.ipdoctest', r'\.Gnuplot', - r'\.frontend.process.winprocess', + r'\.frontend\.process\.winprocess', ] docwriter.write_api_docs(outdir) docwriter.write_index(outdir, 'gen', diff --git a/docs/source/_static/default.css b/docs/source/_static/default.css new file mode 100644 index 0000000..7aa01b7 --- /dev/null +++ b/docs/source/_static/default.css @@ -0,0 +1,507 @@ +/** + * Alternate Sphinx design + * Originally created by Armin Ronacher for Werkzeug, adapted by Georg Brandl. + */ + +body { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif; + font-size: 14px; + letter-spacing: -0.01em; + line-height: 150%; + text-align: center; + /*background-color: #AFC1C4; */ + background-color: #BFD1D4; + color: black; + padding: 0; + border: 1px solid #aaa; + + margin: 0px 80px 0px 80px; + min-width: 740px; +} + +a { + color: #CA7900; + text-decoration: none; +} + +a:hover { + color: #2491CF; +} + +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.015em; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +td.linenos pre { + padding: 0.5em 0; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.01em; +} + +hr { + border: 1px solid #abc; + margin: 2em; +} + +tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; + border: 0; +} + +tt.descclassname { + background-color: transparent; + border: 0; +} + +tt.xref { + background-color: transparent; + font-weight: bold; + border: 0; +} + +a tt { + background-color: transparent; + font-weight: bold; + border: 0; + color: #CA7900; +} + +a tt:hover { + color: #2491CF; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.refcount { + color: #060; +} + +dt:target, +.highlight { + background-color: #fbe54e; +} + +dl.class, dl.function { + border-top: 2px solid #888; +} + +dl.method, dl.attribute { + border-top: 1px solid #aaa; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +pre { + line-height: 120%; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +.first { + margin-top: 0 !important; +} + +div.document { + background-color: white; + text-align: left; + background-image: url(contents.png); + background-repeat: repeat-x; +} + +/* +div.documentwrapper { + width: 100%; +} +*/ + +div.clearer { + clear: both; +} + +div.related h3 { + display: none; +} + +div.related ul { + background-image: url(navigation.png); + height: 2em; + list-style: none; + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 0; + padding-left: 10px; +} + +div.related ul li { + margin: 0; + padding: 0; + height: 2em; + float: left; +} + +div.related ul li.right { + float: right; + margin-right: 5px; +} + +div.related ul li a { + margin: 0; + padding: 0 5px 0 5px; + line-height: 1.75em; + color: #EE9816; +} + +div.related ul li a:hover { + color: #3CA8E7; +} + +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; +} + +div.body a { + text-decoration: underline; +} + +div.sphinxsidebar { + margin: 0; + padding: 0.5em 15px 15px 0; + width: 210px; + float: right; + text-align: left; +/* margin-left: -100%; */ +} + +div.sphinxsidebar h4, div.sphinxsidebar h3 { + margin: 1em 0 0.5em 0; + font-size: 0.9em; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border: 1px solid #86989B; + background-color: #AFC1C4; +} + +div.sphinxsidebar ul { + padding-left: 1.5em; + margin-top: 7px; + list-style: none; + padding: 0; + line-height: 130%; +} + +div.sphinxsidebar ul ul { + list-style: square; + margin-left: 20px; +} + +p { + margin: 0.8em 0 0.5em 0; +} + +p.rubric { + font-weight: bold; +} + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; + font-size: 1.5em; + color: #11557C; +} + +h2 { + margin: 1.3em 0 0.2em 0; + font-size: 1.35em; + padding: 0; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.2em; +} + +h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + color: black!important; +} + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: #aaa!important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: #777; + background-color: #eee; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.footer { + background-color: #E3EFF1; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #86989B; + text-decoration: underline; +} + +div.pagination { + margin-top: 2em; + padding-top: 0.5em; + border-top: 1px solid black; + text-align: center; +} + +div.sphinxsidebar ul.toc { + margin: 1em 0 1em 0; + padding: 0 0 0 0.5em; + list-style: none; +} + +div.sphinxsidebar ul.toc li { + margin: 0.5em 0 0.5em 0; + font-size: 0.9em; + line-height: 130%; +} + +div.sphinxsidebar ul.toc li p { + margin: 0; + padding: 0; +} + +div.sphinxsidebar ul.toc ul { + margin: 0.2em 0 0.2em 0; + padding: 0 0 0 1.8em; +} + +div.sphinxsidebar ul.toc ul li { + padding: 0; +} + +div.admonition, div.warning { + font-size: 0.9em; + margin: 1em 0 0 0; + border: 1px solid #86989B; + background-color: #f7f7f7; +} + +div.admonition p, div.warning p { + margin: 0.5em 1em 0.5em 1em; + padding: 0; +} + +div.admonition pre, div.warning pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition p.admonition-title, +div.warning p.admonition-title { + margin: 0; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border-bottom: 1px solid #86989B; + font-weight: bold; + background-color: #AFC1C4; +} + +div.warning { + border: 1px solid #940000; +} + +div.warning p.admonition-title { + background-color: #CF0000; + border-bottom-color: #940000; +} + +div.admonition ul, div.admonition ol, +div.warning ul, div.warning ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid #ccc; + background-color: #DDEAF0; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + + +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +img.inheritance { + border: 0px +} + +form.pfform { + margin: 10px 0 20px 0; +} + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..1462400 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,23 @@ +{% extends "!layout.html" %} + + +{% block rootrellink %} +
  • home
  • +
  • search
  • +
  • what's new »
  • +{% endblock %} + + +{% block relbar1 %} + +
    +IPython Documentation +
    +{{ super() }} +{% endblock %} + +{# put the sidebar before the body #} +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %}{% endblock %} + diff --git a/docs/source/credits.txt b/docs/source/about/credits.txt similarity index 100% rename from docs/source/credits.txt rename to docs/source/about/credits.txt index 9e92e81..e639448 100644 --- a/docs/source/credits.txt +++ b/docs/source/about/credits.txt @@ -205,3 +205,4 @@ know if we have ommitted your name by accident: Sphinx system used by Python, Matplotlib and many more projects. * [Stefan van der Walt] : support for the new config system. + diff --git a/docs/source/history.txt b/docs/source/about/history.txt similarity index 100% rename from docs/source/history.txt rename to docs/source/about/history.txt diff --git a/docs/source/about/index.txt b/docs/source/about/index.txt new file mode 100644 index 0000000..3abd31b --- /dev/null +++ b/docs/source/about/index.txt @@ -0,0 +1,13 @@ +.. _about_index: + +============= +About IPython +============= + +.. toctree:: + :maxdepth: 1 + + credits + history + license_and_copyright + diff --git a/docs/source/license_and_copyright.txt b/docs/source/about/license_and_copyright.txt similarity index 100% rename from docs/source/license_and_copyright.txt rename to docs/source/about/license_and_copyright.txt index 9c61f1e..fb7d0df 100644 --- a/docs/source/license_and_copyright.txt +++ b/docs/source/about/license_and_copyright.txt @@ -88,4 +88,5 @@ its author/authors have decided to publish the code. Versions of IPython up to and including 0.6.3 were released under the GNU Lesser General Public License (LGPL), available at -http://www.gnu.org/copyleft/lesser.html. \ No newline at end of file +http://www.gnu.org/copyleft/lesser.html. + diff --git a/docs/source/changes.txt b/docs/source/changes.txt deleted file mode 100644 index 2990ade..0000000 --- a/docs/source/changes.txt +++ /dev/null @@ -1,589 +0,0 @@ -.. Developers should add in this file, during each release cycle, information -.. about important changes they've made, in a summary format that's meant for -.. end users. For each release we normally have three sections: features, bug -.. fixes and api breakage. -.. Please remember to credit the authors of the contributions by name, -.. especially when they are new users or developers who do not regularly -.. participate in IPython's development. - -.. _changes: - -========== -What's new -========== - -Development -=========== - -New features ------------- - -* Added a new module :mod:`IPython.lib.inputhook` to manage the integration - with GUI event loops using `PyOS_InputHook`. See the docstrings in this - module or the main IPython docs for details. -* For users, GUI event loop integration is now handled through the new - :command:`%gui` magic command. Type ``%gui?`` at an IPython prompt for - documentation. -* For developers :mod:`IPython.lib.inputhook` provides a simple interface - for managing the event loops in their interactive GUI applications. - Examples can be found in our :dir:`docs/examples/lib` directory. - -Bug fixes ---------- - -* Keyboard interrupts now work with GUI support enabled across all platforms - and all GUI toolkits reliably. - -Backwards incompatible changes ------------------------------- - -* Support for ``qt3`` has been dropped. User's who need this should use - previous versions of IPython. -* Removed :mod:`shellglobals` as it was obsolete. -* Removed all the threaded shells in :mod:`IPython.core.shell`. These are no - longer needed because of the new capabilities in - :mod:`IPython.lib.inputhook`. -* The old threading command line flags (pylab/wthread/etc.) have been - deprecated. Use :mod:`IPython.inputhook` or the new :command:`%gui` magic - command instead. -* New top-level sub-packages have been created: :mod:`IPython.core`, - :mod:`IPython.lib`, :mod:`IPython.utils`, :mod:`IPython.deathrow`, - :mod:`IPython.quarantine`. All existing top-level modules have been - moved to appropriate sub-packages. All internal import statements - have been updated and tests have been added. The build system (setup.py - and friends) have been updated. -* Compatability modules have been created for :mod:`IPython.Shell`, - :mod:`IPython.ipapi` and :mod:`IPython.iplib` that display warnings - and then load the actual implementation from :mod:`IPython.core`. -* :mod:`Extensions` has been moved to :mod:`extensions`. - -Release 0.10 -============ - -This release brings months of slow but steady development, and will be the last -before a major restructuring and cleanup of IPython's internals that is already -under way. For this reason, we hope that 0.10 will be a stable and robust -release so that while users adapt to some of the API changes that will come -with the refactoring that will become IPython 0.11, they can safely use 0.10 in -all existing projects with minimal changes (if any). - -IPython 0.10 is now a medium-sized project, with roughly (as reported by David -Wheeler's :command:`sloccount` utility) 40750 lines of Python code, and a diff -between 0.9.1 and this release that contains almost 28000 lines of code and -documentation. Our documentation, in PDF format, is a 495-page long PDF -document (also available in HTML format, both generated from the same sources). - -Many users and developers contributed code, features, bug reports and ideas to -this release. Please do not hesitate in contacting us if we've failed to -acknowledge your contribution here. In particular, for this release we have -contribution from the following people, a mix of new and regular names (in -alphabetical order by first name): - -* Alexander Clausen: fix #341726. -* Brian Granger: lots of work everywhere (features, bug fixes, etc). -* Daniel Ashbrook: bug report on MemoryError during compilation, now fixed. -* Darren Dale: improvements to documentation build system, feedback, design - ideas. -* Fernando Perez: various places. -* Gaël Varoquaux: core code, ipythonx GUI, design discussions, etc. Lots... -* John Hunter: suggestions, bug fixes, feedback. -* Jorgen Stenarson: work on many fronts, tests, fixes, win32 support, etc. -* Laurent Dufréchou: many improvements to ipython-wx standalone app. -* Lukasz Pankowski: prefilter, `%edit`, demo improvements. -* Matt Foster: TextMate support in `%edit`. -* Nathaniel Smith: fix #237073. -* Pauli Virtanen: fixes and improvements to extensions, documentation. -* Prabhu Ramachandran: improvements to `%timeit`. -* Robert Kern: several extensions. -* Sameer D'Costa: help on critical bug #269966. -* Stephan Peijnik: feedback on Debian compliance and many man pages. -* Steven Bethard: we are now shipping his :mod:`argparse` module. -* Tom Fetherston: many improvements to :mod:`IPython.demo` module. -* Ville Vainio: lots of work everywhere (features, bug fixes, etc). -* Vishal Vasta: ssh support in ipcluster. -* Walter Doerwald: work on the :mod:`IPython.ipipe` system. - -Below we give an overview of new features, bug fixes and backwards-incompatible -changes. For a detailed account of every change made, feel free to view the -project log with :command:`bzr log`. - -New features ------------- - -* New `%paste` magic automatically extracts current contents of clipboard and - pastes it directly, while correctly handling code that is indented or - prepended with `>>>` or `...` python prompt markers. A very useful new - feature contributed by Robert Kern. - -* IPython 'demos', created with the :mod:`IPython.demo` module, can now be - created from files on disk or strings in memory. Other fixes and - improvements to the demo system, by Tom Fetherston. - -* Added :func:`find_cmd` function to :mod:`IPython.platutils` module, to find - commands in a cross-platform manner. - -* Many improvements and fixes to Gaël Varoquaux's :command:`ipythonx`, a - WX-based lightweight IPython instance that can be easily embedded in other WX - applications. These improvements have made it possible to now have an - embedded IPython in Mayavi and other tools. - -* :class:`MultiengineClient` objects now have a :meth:`benchmark` method. - -* The manual now includes a full set of auto-generated API documents from the - code sources, using Sphinx and some of our own support code. We are now - using the `Numpy Documentation Standard`_ for all docstrings, and we have - tried to update as many existing ones as possible to this format. - -* The new :mod:`IPython.Extensions.ipy_pretty` extension by Robert Kern - provides configurable pretty-printing. - -* Many improvements to the :command:`ipython-wx` standalone WX-based IPython - application by Laurent Dufréchou. It can optionally run in a thread, and - this can be toggled at runtime (allowing the loading of Matplotlib in a - running session without ill effects). - -* IPython includes a copy of Steven Bethard's argparse_ in the - :mod:`IPython.external` package, so we can use it internally and it is also - available to any IPython user. By installing it in this manner, we ensure - zero conflicts with any system-wide installation you may already have while - minimizing external dependencies for new users. In IPython 0.10, We ship - argparse version 1.0. - -* An improved and much more robust test suite, that runs groups of tests in - separate subprocesses using either Nose or Twisted's :command:`trial` runner - to ensure proper management of Twisted-using code. The test suite degrades - gracefully if optional dependencies are not available, so that the - :command:`iptest` command can be run with only Nose installed and nothing - else. We also have more and cleaner test decorators to better select tests - depending on runtime conditions, do setup/teardown, etc. - -* The new ipcluster now has a fully working ssh mode that should work on - Linux, Unix and OS X. Thanks to Vishal Vatsa for implementing this! - -* The wonderful TextMate editor can now be used with %edit on OS X. Thanks - to Matt Foster for this patch. - -* The documentation regarding parallel uses of IPython, including MPI and PBS, - has been significantly updated and improved. - -* The developer guidelines in the documentation have been updated to explain - our workflow using :command:`bzr` and Launchpad. - -* Fully refactored :command:`ipcluster` command line program for starting - IPython clusters. This new version is a complete rewrite and 1) is fully - cross platform (we now use Twisted's process management), 2) has much - improved performance, 3) uses subcommands for different types of clusters, 4) - uses argparse for parsing command line options, 5) has better support for - starting clusters using :command:`mpirun`, 6) has experimental support for - starting engines using PBS. It can also reuse FURL files, by appropriately - passing options to its subcommands. However, this new version of ipcluster - should be considered a technology preview. We plan on changing the API in - significant ways before it is final. - -* Full description of the security model added to the docs. - -* cd completer: show bookmarks if no other completions are available. - -* sh profile: easy way to give 'title' to prompt: assign to variable - '_prompt_title'. It looks like this:: - - [~]|1> _prompt_title = 'sudo!' - sudo![~]|2> - -* %edit: If you do '%edit pasted_block', pasted_block variable gets updated - with new data (so repeated editing makes sense) - -.. _Numpy Documentation Standard: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard - -.. _argparse: http://code.google.com/p/argparse/ - -Bug fixes ---------- - -* Fix #368719, removed top-level debian/ directory to make the job of Debian - packagers easier. - -* Fix #291143 by including man pages contributed by Stephan Peijnik from the - Debian project. - -* Fix #358202, effectively a race condition, by properly synchronizing file - creation at cluster startup time. - -* `%timeit` now handles correctly functions that take a long time to execute - even the first time, by not repeating them. - -* Fix #239054, releasing of references after exiting. - -* Fix #341726, thanks to Alexander Clausen. - -* Fix #269966. This long-standing and very difficult bug (which is actually a - problem in Python itself) meant long-running sessions would inevitably grow - in memory size, often with catastrophic consequences if users had large - objects in their scripts. Now, using `%run` repeatedly should not cause any - memory leaks. Special thanks to John Hunter and Sameer D'Costa for their - help with this bug. - -* Fix #295371, bug in `%history`. - -* Improved support for py2exe. - -* Fix #270856: IPython hangs with PyGTK - -* Fix #270998: A magic with no docstring breaks the '%magic magic' - -* fix #271684: -c startup commands screw up raw vs. native history - -* Numerous bugs on Windows with the new ipcluster have been fixed. - -* The ipengine and ipcontroller scripts now handle missing furl files - more gracefully by giving better error messages. - -* %rehashx: Aliases no longer contain dots. python3.0 binary - will create alias python30. Fixes: - #259716 "commands with dots in them don't work" - -* %cpaste: %cpaste -r repeats the last pasted block. - The block is assigned to pasted_block even if code - raises exception. - -* Bug #274067 'The code in get_home_dir is broken for py2exe' was - fixed. - -* Many other small bug fixes not listed here by number (see the bzr log for - more info). - -Backwards incompatible changes ------------------------------- - -* `ipykit` and related files were unmaintained and have been removed. - -* The :func:`IPython.genutils.doctest_reload` does not actually call - `reload(doctest)` anymore, as this was causing many problems with the test - suite. It still resets `doctest.master` to None. - -* While we have not deliberately broken Python 2.4 compatibility, only minor - testing was done with Python 2.4, while 2.5 and 2.6 were fully tested. But - if you encounter problems with 2.4, please do report them as bugs. - -* The :command:`ipcluster` now requires a mode argument; for example to start a - cluster on the local machine with 4 engines, you must now type:: - - $ ipcluster local -n 4 - -* The controller now has a ``-r`` flag that needs to be used if you want to - reuse existing furl files. Otherwise they are deleted (the default). - -* Remove ipy_leo.py. You can use :command:`easy_install ipython-extension` to - get it. (done to decouple it from ipython release cycle) - - -Release 0.9.1 -============= - -This release was quickly made to restore compatibility with Python 2.4, which -version 0.9 accidentally broke. No new features were introduced, other than -some additional testing support for internal use. - - -Release 0.9 -=========== - -New features ------------- - -* All furl files and security certificates are now put in a read-only - directory named ~./ipython/security. - -* A single function :func:`get_ipython_dir`, in :mod:`IPython.genutils` that - determines the user's IPython directory in a robust manner. - -* Laurent's WX application has been given a top-level script called - ipython-wx, and it has received numerous fixes. We expect this code to be - architecturally better integrated with Gael's WX 'ipython widget' over the - next few releases. - -* The Editor synchronization work by Vivian De Smedt has been merged in. This - code adds a number of new editor hooks to synchronize with editors under - Windows. - -* A new, still experimental but highly functional, WX shell by Gael Varoquaux. - This work was sponsored by Enthought, and while it's still very new, it is - based on a more cleanly organized arhictecture of the various IPython - components. We will continue to develop this over the next few releases as a - model for GUI components that use IPython. - -* Another GUI frontend, Cocoa based (Cocoa is the OSX native GUI framework), - authored by Barry Wark. Currently the WX and the Cocoa ones have slightly - different internal organizations, but the whole team is working on finding - what the right abstraction points are for a unified codebase. - -* As part of the frontend work, Barry Wark also implemented an experimental - event notification system that various ipython components can use. In the - next release the implications and use patterns of this system regarding the - various GUI options will be worked out. - -* IPython finally has a full test system, that can test docstrings with - IPython-specific functionality. There are still a few pieces missing for it - to be widely accessible to all users (so they can run the test suite at any - time and report problems), but it now works for the developers. We are - working hard on continuing to improve it, as this was probably IPython's - major Achilles heel (the lack of proper test coverage made it effectively - impossible to do large-scale refactoring). The full test suite can now - be run using the :command:`iptest` command line program. - -* The notion of a task has been completely reworked. An `ITask` interface has - been created. This interface defines the methods that tasks need to - implement. These methods are now responsible for things like submitting - tasks and processing results. There are two basic task types: - :class:`IPython.kernel.task.StringTask` (this is the old `Task` object, but - renamed) and the new :class:`IPython.kernel.task.MapTask`, which is based on - a function. - -* A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to - standardize the idea of a `map` method. This interface has a single `map` - method that has the same syntax as the built-in `map`. We have also defined - a `mapper` factory interface that creates objects that implement - :class:`IPython.kernel.mapper.IMapper` for different controllers. Both the - multiengine and task controller now have mapping capabilties. - -* The parallel function capabilities have been reworks. The major changes are - that i) there is now an `@parallel` magic that creates parallel functions, - ii) the syntax for mulitple variable follows that of `map`, iii) both the - multiengine and task controller now have a parallel function implementation. - -* All of the parallel computing capabilities from `ipython1-dev` have been - merged into IPython proper. This resulted in the following new subpackages: - :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`, - :mod:`IPython.tools` and :mod:`IPython.testing`. - -* As part of merging in the `ipython1-dev` stuff, the `setup.py` script and - friends have been completely refactored. Now we are checking for - dependencies using the approach that matplotlib uses. - -* The documentation has been completely reorganized to accept the - documentation from `ipython1-dev`. - -* We have switched to using Foolscap for all of our network protocols in - :mod:`IPython.kernel`. This gives us secure connections that are both - encrypted and authenticated. - -* We have a brand new `COPYING.txt` files that describes the IPython license - and copyright. The biggest change is that we are putting "The IPython - Development Team" as the copyright holder. We give more details about - exactly what this means in this file. All developer should read this and use - the new banner in all IPython source code files. - -* sh profile: ./foo runs foo as system command, no need to do !./foo anymore - -* String lists now support ``sort(field, nums = True)`` method (to easily sort - system command output). Try it with ``a = !ls -l ; a.sort(1, nums=1)``. - -* '%cpaste foo' now assigns the pasted block as string list, instead of string - -* The ipcluster script now run by default with no security. This is done - because the main usage of the script is for starting things on localhost. - Eventually when ipcluster is able to start things on other hosts, we will put - security back. - -* 'cd --foo' searches directory history for string foo, and jumps to that dir. - Last part of dir name is checked first. If no matches for that are found, - look at the whole path. - - -Bug fixes ---------- - -* The Windows installer has been fixed. Now all IPython scripts have ``.bat`` - versions created. Also, the Start Menu shortcuts have been updated. - -* The colors escapes in the multiengine client are now turned off on win32 as - they don't print correctly. - -* The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing - mpi_import_statement incorrectly, which was leading the engine to crash when - mpi was enabled. - -* A few subpackages had missing ``__init__.py`` files. - -* The documentation is only created if Sphinx is found. Previously, the - ``setup.py`` script would fail if it was missing. - -* Greedy ``cd`` completion has been disabled again (it was enabled in 0.8.4) as - it caused problems on certain platforms. - - -Backwards incompatible changes ------------------------------- - -* The ``clusterfile`` options of the :command:`ipcluster` command has been - removed as it was not working and it will be replaced soon by something much - more robust. - -* The :mod:`IPython.kernel` configuration now properly find the user's - IPython directory. - -* In ipapi, the :func:`make_user_ns` function has been replaced with - :func:`make_user_namespaces`, to support dict subclasses in namespace - creation. - -* :class:`IPython.kernel.client.Task` has been renamed - :class:`IPython.kernel.client.StringTask` to make way for new task types. - -* The keyword argument `style` has been renamed `dist` in `scatter`, `gather` - and `map`. - -* Renamed the values that the rename `dist` keyword argument can have from - `'basic'` to `'b'`. - -* IPython has a larger set of dependencies if you want all of its capabilities. - See the `setup.py` script for details. - -* The constructors for :class:`IPython.kernel.client.MultiEngineClient` and - :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple. - Instead they take the filename of a file that contains the FURL for that - client. If the FURL file is in your IPYTHONDIR, it will be found automatically - and the constructor can be left empty. - -* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created - using the factory functions :func:`get_multiengine_client` and - :func:`get_task_client`. These return a `Deferred` to the actual client. - -* The command line options to `ipcontroller` and `ipengine` have changed to - reflect the new Foolscap network protocol and the FURL files. Please see the - help for these scripts for details. - -* The configuration files for the kernel have changed because of the Foolscap - stuff. If you were using custom config files before, you should delete them - and regenerate new ones. - -Changes merged in from IPython1 -------------------------------- - -New features -............ - -* Much improved ``setup.py`` and ``setupegg.py`` scripts. Because Twisted and - zope.interface are now easy installable, we can declare them as dependencies - in our setupegg.py script. - -* IPython is now compatible with Twisted 2.5.0 and 8.x. - -* Added a new example of how to use :mod:`ipython1.kernel.asynclient`. - -* Initial draft of a process daemon in :mod:`ipython1.daemon`. This has not - been merged into IPython and is still in `ipython1-dev`. - -* The ``TaskController`` now has methods for getting the queue status. - -* The ``TaskResult`` objects not have information about how long the task - took to run. - -* We are attaching additional attributes to exceptions ``(_ipython_*)`` that - we use to carry additional info around. - -* New top-level module :mod:`asyncclient` that has asynchronous versions (that - return deferreds) of the client classes. This is designed to users who want - to run their own Twisted reactor. - -* All the clients in :mod:`client` are now based on Twisted. This is done by - running the Twisted reactor in a separate thread and using the - :func:`blockingCallFromThread` function that is in recent versions of Twisted. - -* Functions can now be pushed/pulled to/from engines using - :meth:`MultiEngineClient.push_function` and - :meth:`MultiEngineClient.pull_function`. - -* Gather/scatter are now implemented in the client to reduce the work load - of the controller and improve performance. - -* Complete rewrite of the IPython docuementation. All of the documentation - from the IPython website has been moved into docs/source as restructured - text documents. PDF and HTML documentation are being generated using - Sphinx. - -* New developer oriented documentation: development guidelines and roadmap. - -* Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt`` - file that is organized by release and is meant to provide something more - relevant for users. - -Bug fixes -......... - -* Created a proper ``MANIFEST.in`` file to create source distributions. - -* Fixed a bug in the ``MultiEngine`` interface. Previously, multi-engine - actions were being collected with a :class:`DeferredList` with - ``fireononeerrback=1``. This meant that methods were returning - before all engines had given their results. This was causing extremely odd - bugs in certain cases. To fix this problem, we have 1) set - ``fireononeerrback=0`` to make sure all results (or exceptions) are in - before returning and 2) introduced a :exc:`CompositeError` exception - that wraps all of the engine exceptions. This is a huge change as it means - that users will have to catch :exc:`CompositeError` rather than the actual - exception. - -Backwards incompatible changes -.............................. - -* All names have been renamed to conform to the lowercase_with_underscore - convention. This will require users to change references to all names like - ``queueStatus`` to ``queue_status``. - -* Previously, methods like :meth:`MultiEngineClient.push` and - :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``. This was - becoming a problem as we weren't able to introduce new keyword arguments into - the API. Now these methods simple take a dict or sequence. This has also - allowed us to get rid of the ``*All`` methods like :meth:`pushAll` and - :meth:`pullAll`. These things are now handled with the ``targets`` keyword - argument that defaults to ``'all'``. - -* The :attr:`MultiEngineClient.magicTargets` has been renamed to - :attr:`MultiEngineClient.targets`. - -* All methods in the MultiEngine interface now accept the optional keyword - argument ``block``. - -* Renamed :class:`RemoteController` to :class:`MultiEngineClient` and - :class:`TaskController` to :class:`TaskClient`. - -* Renamed the top-level module from :mod:`api` to :mod:`client`. - -* Most methods in the multiengine interface now raise a :exc:`CompositeError` - exception that wraps the user's exceptions, rather than just raising the raw - user's exception. - -* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` - and ``pull``. - - -Release 0.8.4 -============= - -This was a quick release to fix an unfortunate bug that slipped into the 0.8.3 -release. The ``--twisted`` option was disabled, as it turned out to be broken -across several platforms. - - -Release 0.8.3 -============= - -* pydb is now disabled by default (due to %run -d problems). You can enable - it by passing -pydb command line argument to IPython. Note that setting - it in config file won't work. - - -Release 0.8.2 -============= - -* %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory - and jumps to /foo. The current behaviour is closer to the documented - behaviour, and should not trip anyone. - - -Older releases -============== - -Changes in earlier releases of IPython are described in the older file -``ChangeLog``. Please refer to this document for details. - diff --git a/docs/source/conf.py b/docs/source/conf.py index e4f948b..14806f8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -35,15 +35,16 @@ execfile('../../IPython/core/release.py',iprelease) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.doctest', - - 'only_directives', - 'inheritance_diagram', - 'ipython_console_highlighting', - # 'plot_directive', # disabled for now, needs matplotlib - 'numpydoc', # to preprocess docstrings - ] +extensions = [ + # 'matplotlib.sphinxext.mathmpl', + 'matplotlib.sphinxext.only_directives', + # 'matplotlib.sphinxext.plot_directive', + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'inheritance_diagram', + 'ipython_console_highlighting', + 'numpydoc', # to preprocess docstrings +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/source/config/customization.txt b/docs/source/config/customization.txt index 8211b4c..2d66648 100644 --- a/docs/source/config/customization.txt +++ b/docs/source/config/customization.txt @@ -283,4 +283,5 @@ 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. \ No newline at end of file +point, and then add further customizations. + diff --git a/docs/source/config/index.txt b/docs/source/config/index.txt index 1214811..c6b3e87 100644 --- a/docs/source/config/index.txt +++ b/docs/source/config/index.txt @@ -8,3 +8,4 @@ Configuration and customization initial_config.txt customization.txt new_config.txt + diff --git a/docs/source/config/initial_config.txt b/docs/source/config/initial_config.txt index c9c12e9..df1a1e7 100644 --- a/docs/source/config/initial_config.txt +++ b/docs/source/config/initial_config.txt @@ -247,3 +247,4 @@ Notes: * 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/new_config.txt b/docs/source/config/new_config.txt index 569888a..3f25b35 100644 --- a/docs/source/config/new_config.txt +++ b/docs/source/config/new_config.txt @@ -24,4 +24,5 @@ To create these files for the first time, do the following:: But, you should only need to do this if you need to modify the defaults. If needed repeat this process with the ``notebook`` and ``core`` configuration as well. If you are running into problems with IPython, you might try deleting these configuration -files. \ No newline at end of file +files. + diff --git a/docs/source/development/coding_guide.txt b/docs/source/development/coding_guide.txt index 761fdbb..4d1de1f 100644 --- a/docs/source/development/coding_guide.txt +++ b/docs/source/development/coding_guide.txt @@ -139,3 +139,4 @@ are interested in working on this part of IPython. The current prototype of .. _.ini: http://docs.python.org/lib/module-ConfigParser.html .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html .. _Traits: http://code.enthought.com/traits/ + diff --git a/docs/source/development/config_blueprint.txt b/docs/source/development/config_blueprint.txt index caa5d13..fdfd31b 100644 --- a/docs/source/development/config_blueprint.txt +++ b/docs/source/development/config_blueprint.txt @@ -31,3 +31,4 @@ There are a number of things that complicate this: different host. Ahhhh! * Our configurations are not singletons. A given user will likely have many different configurations for different clusters. + diff --git a/docs/source/development/doc_guide.txt b/docs/source/development/doc_guide.txt index 9a0e453..00ae59f 100644 --- a/docs/source/development/doc_guide.txt +++ b/docs/source/development/doc_guide.txt @@ -101,3 +101,4 @@ machinery to process reStructuredText): - `Docstring Processing System Framework `_ - `Docutils Design Specification `_ + diff --git a/docs/source/development/index.txt b/docs/source/development/index.txt index 97640a3..ae031d9 100644 --- a/docs/source/development/index.txt +++ b/docs/source/development/index.txt @@ -13,3 +13,4 @@ notification_blueprint.txt config_blueprint.txt reorg.txt + diff --git a/docs/source/development/notification_blueprint.txt b/docs/source/development/notification_blueprint.txt index 8b0dd75..b665368 100644 --- a/docs/source/development/notification_blueprint.txt +++ b/docs/source/development/notification_blueprint.txt @@ -78,6 +78,31 @@ Like magic, Dwight's frontend is able to provide output, even during long-running calculations. Now if Jim could just convince Dwight to use Twisted... - 2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is stuck in the stone age, his frontend will be written in a new Fortran-like dialect of python and will run only from the command line. Because he doesn't need any fancy notification system and is used to worrying about every cycle on his rat-wheel powered mini, Boss Hog is adamant that the new notification system not produce any performance penalty. As they say in Hazard county, there's no such thing as a free lunch. If he wanted zero overhead, he should have kept using IPython 0.8. Instead, those tricky Duke boys slide in a suped-up bridge-out jumpin' awkwardly confederate-lovin' notification module that imparts only a constant (and small) performance penalty when the Interpreter (or any other object) fires an event for which there are no registered observers. Of course, the same notificaiton-enabled Interpreter can then be used in frontends that require notifications, thus saving the IPython project from a nasty civil war. +2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is +stuck in the stone age, his frontend will be written in a new Fortran-like +dialect of python and will run only from the command line. Because he doesn't +need any fancy notification system and is used to worrying about every cycle +on his rat-wheel powered mini, Boss Hog is adamant that the new notification +system not produce any performance penalty. As they say in Hazard county, +there's no such thing as a free lunch. If he wanted zero overhead, he should +have kept using IPython 0.8. Instead, those tricky Duke boys slide in a +suped-up bridge-out jumpin' awkwardly confederate-lovin' notification module +that imparts only a constant (and small) performance penalty when the +Interpreter (or any other object) fires an event for which there are no +registered observers. Of course, the same notificaiton-enabled Interpreter can +then be used in frontends that require notifications, thus saving the IPython +project from a nasty civil war. - 3. Barry is wrting a frontend for the IPython project. Because Barry's front end is the *new hotness*, it uses an asynchronous event model to communicate with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the :mod:`IPython.kernel.core.notification` module, Barry's frontend can register for notifications from the interpreter that are delivered asynchronously. Even if Barry's frontend is running on a separate process or even host from the Interpreter, the notifications are delivered, as if by dark and twisted magic. Just like Dwight's frontend, Barry's frontend can now recieve notifications of e.g. writing to stdout/stderr, opening/closing an external file, an exception in the executing code, etc. \ No newline at end of file +3. Barry is wrting a frontend for the IPython project. Because Barry's front +end is the *new hotness*, it uses an asynchronous event model to communicate +with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the +IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the +:mod:`IPython.kernel.notification` module, an asynchronous wrapper on the +:mod:`IPython.kernel.core.notification` module, Barry's frontend can register +for notifications from the interpreter that are delivered asynchronously. Even +if Barry's frontend is running on a separate process or even host from the +Interpreter, the notifications are delivered, as if by dark and twisted magic. +Just like Dwight's frontend, Barry's frontend can now recieve notifications of +e.g. writing to stdout/stderr, opening/closing an external file, an exception +in the executing code, etc. + diff --git a/docs/source/development/overview.txt b/docs/source/development/overview.txt index a39cca7..30cfcc7 100644 --- a/docs/source/development/overview.txt +++ b/docs/source/development/overview.txt @@ -515,3 +515,4 @@ version 0.11 at least, we will retain Python 2.5 compatibility. .. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html .. [Sphinx] Sphinx. http://sphinx.pocoo.org/ .. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/ + diff --git a/docs/source/development/reorg.txt b/docs/source/development/reorg.txt index 6ae099d..8db81eb 100644 --- a/docs/source/development/reorg.txt +++ b/docs/source/development/reorg.txt @@ -82,3 +82,4 @@ Status ====== 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 4a6123b..56ba275 100644 --- a/docs/source/development/roadmap.txt +++ b/docs/source/development/roadmap.txt @@ -92,5 +92,3 @@ Currently, we have a number of performance issues in :mod:`IPython.kernel`: separate the controller itself into multiple processes, one for the core controller and one each for the controller interfaces. - - diff --git a/docs/source/faq.txt b/docs/source/faq.txt index 321cb06..c30adb1 100644 --- a/docs/source/faq.txt +++ b/docs/source/faq.txt @@ -94,12 +94,3 @@ handling the data movement. Here are some ideas: Isn't Python slow to be used for high-performance parallel computing? --------------------------------------------------------------------- - - - - - - - - - diff --git a/docs/source/index.txt b/docs/source/index.txt index 2180bc9..a2874a8 100644 --- a/docs/source/index.txt +++ b/docs/source/index.txt @@ -7,25 +7,28 @@ IPython Documentation :Release: |release| :Date: |today| - Contents: +Welcome to the official IPython documentation. This document describes the +various parts of IPython that are relevant to both users and developers. + +Contents +======== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 overview.txt + whatsnew/index.txt install/index.txt interactive/index.txt parallel/index.txt config/index.txt - faq.txt - history.txt - changes.txt development/index.txt api/index.txt - license_and_copyright.txt - credits.txt + faq.txt + about/index.txt .. htmlonly:: * :ref:`genindex` * :ref:`modindex` * :ref:`search` + diff --git a/docs/source/install/index.txt b/docs/source/install/index.txt index f6cd618..9879894 100644 --- a/docs/source/install/index.txt +++ b/docs/source/install/index.txt @@ -8,3 +8,4 @@ Installation :maxdepth: 2 install.txt + diff --git a/docs/source/install/install.txt b/docs/source/install/install.txt index 971c4eb..d513d79 100644 --- a/docs/source/install/install.txt +++ b/docs/source/install/install.txt @@ -291,3 +291,4 @@ binary installer is available on the `wxPython website .. [ZopeInterface] http://pypi.python.org/pypi/zope.interface .. [Foolscap] Foolscap network protocol. http://foolscap.lothar.com/trac .. [pyOpenSSL] pyOpenSSL. http://pyopenssl.sourceforge.net + diff --git a/docs/source/interactive/extension_api.txt b/docs/source/interactive/extension_api.txt index 779829b..5c367aa 100644 --- a/docs/source/interactive/extension_api.txt +++ b/docs/source/interactive/extension_api.txt @@ -249,4 +249,5 @@ ipy_server.py ipy_signals.py ipy_stock_completers.py ipy_system_conf.py ipy_traits_completer.py ipy_vimserver.py ipy_which.py ipy_workdir.py jobctrl.py ledit.py numeric_formats.py PhysicalQInput.py PhysicalQInteractive.py pickleshare.py -pspersistence.py win32clip.py __init__.py \ No newline at end of file +pspersistence.py win32clip.py __init__.py + diff --git a/docs/source/interactive/index.txt b/docs/source/interactive/index.txt index ae45bc5..0e0dff9 100644 --- a/docs/source/interactive/index.txt +++ b/docs/source/interactive/index.txt @@ -9,3 +9,4 @@ Using IPython for interactive work reference.txt shell.txt extension_api.txt + diff --git a/docs/source/interactive/shell.txt b/docs/source/interactive/shell.txt index e3df967..0c39d16 100644 --- a/docs/source/interactive/shell.txt +++ b/docs/source/interactive/shell.txt @@ -281,4 +281,5 @@ single space (for convenient passing to system commands). The '.n' property return one string where the lines are separated by '\n' (i.e. the original output of the function). If the items in string list are file names, '.p' can be used to get a list of "path" objects -for convenient file manipulation. \ No newline at end of file +for convenient file manipulation. + diff --git a/docs/source/interactive/tutorial.txt b/docs/source/interactive/tutorial.txt index 23a2854..21381d7 100644 --- a/docs/source/interactive/tutorial.txt +++ b/docs/source/interactive/tutorial.txt @@ -313,3 +313,5 @@ organized by project and date. Contribute your own: If you have your own favorite tip on using IPython efficiently for a certain task (especially things which can't be done in the normal Python interpreter), don't hesitate to send it! + + diff --git a/docs/source/overview.txt b/docs/source/overview.txt index 184a0ea..a3250d4 100644 --- a/docs/source/overview.txt +++ b/docs/source/overview.txt @@ -218,9 +218,10 @@ for parallel computing. Portability and Python requirements ----------------------------------- -As of the 0.9 release, IPython requires Python 2.4 or greater. We have -not begun to test IPython on Python 2.6 or 3.0, but we expect it will -work with some minor changes. +As of the 0.11 release, IPython works with either Python 2.5 or 2.6. +Versions 0.9 and 0.10 worked with Python 2.4 as well. We have not begun +the test and port IPython to 3.0. Our plan is to gradually drop Python 2.5 +support and then begin the transition to strict 2.6 and 3.0. IPython is known to work on the following operating systems: @@ -229,4 +230,5 @@ IPython is known to work on the following operating systems: * Mac OS X * Windows (CygWin, XP, Vista, etc.) -See :ref:`here ` for instructions on how to install IPython. \ No newline at end of file +See :ref:`here ` for instructions on how to install IPython. + diff --git a/docs/source/parallel/index.txt b/docs/source/parallel/index.txt index e68ee0a..61ab969 100644 --- a/docs/source/parallel/index.txt +++ b/docs/source/parallel/index.txt @@ -13,3 +13,5 @@ Using IPython for parallel computing parallel_task.txt parallel_mpi.txt parallel_security.txt + + diff --git a/docs/source/parallel/parallel_mpi.txt b/docs/source/parallel/parallel_mpi.txt index b34bfa2..45fc61f 100644 --- a/docs/source/parallel/parallel_mpi.txt +++ b/docs/source/parallel/parallel_mpi.txt @@ -174,3 +174,5 @@ compiled C, C++ and Fortran libraries that have been exposed to Python. .. [mpi4py] MPI for Python. mpi4py: http://mpi4py.scipy.org/ .. [OpenMPI] Open MPI. http://www.open-mpi.org/ .. [PyTrilinos] PyTrilinos. http://trilinos.sandia.gov/packages/pytrilinos/ + + diff --git a/docs/source/parallel/parallel_process.txt b/docs/source/parallel/parallel_process.txt index 8e43ed5..533a038 100644 --- a/docs/source/parallel/parallel_process.txt +++ b/docs/source/parallel/parallel_process.txt @@ -385,3 +385,5 @@ the log files to us will often help us to debug any problems. .. [PBS] Portable Batch System. http://www.openpbs.org/ .. [SSH] SSH-Agent http://en.wikipedia.org/wiki/Ssh-agent + + diff --git a/docs/source/parallel/parallel_security.txt b/docs/source/parallel/parallel_security.txt index 9112e48..ac95119 100644 --- a/docs/source/parallel/parallel_security.txt +++ b/docs/source/parallel/parallel_security.txt @@ -362,3 +362,5 @@ authentication steps that the CLIENT and SERVER perform after an encrypted channel is established. .. [RFC5246] + + diff --git a/docs/source/parallel/parallel_task.txt b/docs/source/parallel/parallel_task.txt index 6fb0ecd..e88cbd9 100644 --- a/docs/source/parallel/parallel_task.txt +++ b/docs/source/parallel/parallel_task.txt @@ -118,3 +118,4 @@ We are in the process of developing more detailed information about the task interface. For now, the docstrings of the :class:`TaskClient`, :class:`StringTask` and :class:`MapTask` classes should be consulted. + diff --git a/docs/source/whatsnew/development.txt b/docs/source/whatsnew/development.txt new file mode 100644 index 0000000..65f398a --- /dev/null +++ b/docs/source/whatsnew/development.txt @@ -0,0 +1,49 @@ +================================================ +Development version +================================================ + +Main `ipython` branch +===================== + +New features +------------ + +* Added a new module :mod:`IPython.lib.inputhook` to manage the integration + with GUI event loops using `PyOS_InputHook`. See the docstrings in this + module or the main IPython docs for details. +* For users, GUI event loop integration is now handled through the new + :command:`%gui` magic command. Type ``%gui?`` at an IPython prompt for + documentation. +* For developers :mod:`IPython.lib.inputhook` provides a simple interface + for managing the event loops in their interactive GUI applications. + Examples can be found in our :file:`docs/examples/lib` directory. + +Bug fixes +--------- + +* Keyboard interrupts now work with GUI support enabled across all platforms + and all GUI toolkits reliably. + +Backwards incompatible changes +------------------------------ + +* Support for ``qt3`` has been dropped. User's who need this should use + previous versions of IPython. +* Removed :mod:`shellglobals` as it was obsolete. +* Removed all the threaded shells in :mod:`IPython.core.shell`. These are no + longer needed because of the new capabilities in + :mod:`IPython.lib.inputhook`. +* The old threading command line flags (pylab/wthread/etc.) have been + deprecated. Use :mod:`IPython.inputhook` or the new :command:`%gui` magic + command instead. +* New top-level sub-packages have been created: :mod:`IPython.core`, + :mod:`IPython.lib`, :mod:`IPython.utils`, :mod:`IPython.deathrow`, + :mod:`IPython.quarantine`. All existing top-level modules have been + moved to appropriate sub-packages. All internal import statements + have been updated and tests have been added. The build system (setup.py + and friends) have been updated. +* Compatability modules have been created for :mod:`IPython.Shell`, + :mod:`IPython.ipapi` and :mod:`IPython.iplib` that display warnings + and then load the actual implementation from :mod:`IPython.core`. +* :mod:`Extensions` has been moved to :mod:`extensions`. + diff --git a/docs/source/whatsnew/index.txt b/docs/source/whatsnew/index.txt new file mode 100644 index 0000000..c36e178 --- /dev/null +++ b/docs/source/whatsnew/index.txt @@ -0,0 +1,23 @@ +.. Developers should add in this file, during each release cycle, information +.. about important changes they've made, in a summary format that's meant for +.. end users. For each release we normally have three sections: features, bug +.. fixes and api breakage. +.. Please remember to credit the authors of the contributions by name, +.. especially when they are new users or developers who do not regularly +.. participate in IPython's development. + +.. _whatsnew_index: + +===================== +What's new in IPython +===================== + +.. toctree:: + :maxdepth: 1 + + development + version0.10 + version0.9 + version0.8 + + diff --git a/docs/source/whatsnew/version0.10.txt b/docs/source/whatsnew/version0.10.txt new file mode 100644 index 0000000..d23f813 --- /dev/null +++ b/docs/source/whatsnew/version0.10.txt @@ -0,0 +1,223 @@ +======================================== +0.10 series +======================================== + +Release 0.10 +============ + +This release brings months of slow but steady development, and will be the last +before a major restructuring and cleanup of IPython's internals that is already +under way. For this reason, we hope that 0.10 will be a stable and robust +release so that while users adapt to some of the API changes that will come +with the refactoring that will become IPython 0.11, they can safely use 0.10 in +all existing projects with minimal changes (if any). + +IPython 0.10 is now a medium-sized project, with roughly (as reported by David +Wheeler's :command:`sloccount` utility) 40750 lines of Python code, and a diff +between 0.9.1 and this release that contains almost 28000 lines of code and +documentation. Our documentation, in PDF format, is a 495-page long PDF +document (also available in HTML format, both generated from the same sources). + +Many users and developers contributed code, features, bug reports and ideas to +this release. Please do not hesitate in contacting us if we've failed to +acknowledge your contribution here. In particular, for this release we have +contribution from the following people, a mix of new and regular names (in +alphabetical order by first name): + +* Alexander Clausen: fix #341726. +* Brian Granger: lots of work everywhere (features, bug fixes, etc). +* Daniel Ashbrook: bug report on MemoryError during compilation, now fixed. +* Darren Dale: improvements to documentation build system, feedback, design + ideas. +* Fernando Perez: various places. +* Gaël Varoquaux: core code, ipythonx GUI, design discussions, etc. Lots... +* John Hunter: suggestions, bug fixes, feedback. +* Jorgen Stenarson: work on many fronts, tests, fixes, win32 support, etc. +* Laurent Dufréchou: many improvements to ipython-wx standalone app. +* Lukasz Pankowski: prefilter, `%edit`, demo improvements. +* Matt Foster: TextMate support in `%edit`. +* Nathaniel Smith: fix #237073. +* Pauli Virtanen: fixes and improvements to extensions, documentation. +* Prabhu Ramachandran: improvements to `%timeit`. +* Robert Kern: several extensions. +* Sameer D'Costa: help on critical bug #269966. +* Stephan Peijnik: feedback on Debian compliance and many man pages. +* Steven Bethard: we are now shipping his :mod:`argparse` module. +* Tom Fetherston: many improvements to :mod:`IPython.demo` module. +* Ville Vainio: lots of work everywhere (features, bug fixes, etc). +* Vishal Vasta: ssh support in ipcluster. +* Walter Doerwald: work on the :mod:`IPython.ipipe` system. + +Below we give an overview of new features, bug fixes and backwards-incompatible +changes. For a detailed account of every change made, feel free to view the +project log with :command:`bzr log`. + +New features +------------ + +* New `%paste` magic automatically extracts current contents of clipboard and + pastes it directly, while correctly handling code that is indented or + prepended with `>>>` or `...` python prompt markers. A very useful new + feature contributed by Robert Kern. + +* IPython 'demos', created with the :mod:`IPython.demo` module, can now be + created from files on disk or strings in memory. Other fixes and + improvements to the demo system, by Tom Fetherston. + +* Added :func:`find_cmd` function to :mod:`IPython.platutils` module, to find + commands in a cross-platform manner. + +* Many improvements and fixes to Gaël Varoquaux's :command:`ipythonx`, a + WX-based lightweight IPython instance that can be easily embedded in other WX + applications. These improvements have made it possible to now have an + embedded IPython in Mayavi and other tools. + +* :class:`MultiengineClient` objects now have a :meth:`benchmark` method. + +* The manual now includes a full set of auto-generated API documents from the + code sources, using Sphinx and some of our own support code. We are now + using the `Numpy Documentation Standard`_ for all docstrings, and we have + tried to update as many existing ones as possible to this format. + +* The new :mod:`IPython.Extensions.ipy_pretty` extension by Robert Kern + provides configurable pretty-printing. + +* Many improvements to the :command:`ipython-wx` standalone WX-based IPython + application by Laurent Dufréchou. It can optionally run in a thread, and + this can be toggled at runtime (allowing the loading of Matplotlib in a + running session without ill effects). + +* IPython includes a copy of Steven Bethard's argparse_ in the + :mod:`IPython.external` package, so we can use it internally and it is also + available to any IPython user. By installing it in this manner, we ensure + zero conflicts with any system-wide installation you may already have while + minimizing external dependencies for new users. In IPython 0.10, We ship + argparse version 1.0. + +* An improved and much more robust test suite, that runs groups of tests in + separate subprocesses using either Nose or Twisted's :command:`trial` runner + to ensure proper management of Twisted-using code. The test suite degrades + gracefully if optional dependencies are not available, so that the + :command:`iptest` command can be run with only Nose installed and nothing + else. We also have more and cleaner test decorators to better select tests + depending on runtime conditions, do setup/teardown, etc. + +* The new ipcluster now has a fully working ssh mode that should work on + Linux, Unix and OS X. Thanks to Vishal Vatsa for implementing this! + +* The wonderful TextMate editor can now be used with %edit on OS X. Thanks + to Matt Foster for this patch. + +* The documentation regarding parallel uses of IPython, including MPI and PBS, + has been significantly updated and improved. + +* The developer guidelines in the documentation have been updated to explain + our workflow using :command:`bzr` and Launchpad. + +* Fully refactored :command:`ipcluster` command line program for starting + IPython clusters. This new version is a complete rewrite and 1) is fully + cross platform (we now use Twisted's process management), 2) has much + improved performance, 3) uses subcommands for different types of clusters, 4) + uses argparse for parsing command line options, 5) has better support for + starting clusters using :command:`mpirun`, 6) has experimental support for + starting engines using PBS. It can also reuse FURL files, by appropriately + passing options to its subcommands. However, this new version of ipcluster + should be considered a technology preview. We plan on changing the API in + significant ways before it is final. + +* Full description of the security model added to the docs. + +* cd completer: show bookmarks if no other completions are available. + +* sh profile: easy way to give 'title' to prompt: assign to variable + '_prompt_title'. It looks like this:: + + [~]|1> _prompt_title = 'sudo!' + sudo![~]|2> + +* %edit: If you do '%edit pasted_block', pasted_block variable gets updated + with new data (so repeated editing makes sense) + +.. _Numpy Documentation Standard: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard + +.. _argparse: http://code.google.com/p/argparse/ + +Bug fixes +--------- + +* Fix #368719, removed top-level debian/ directory to make the job of Debian + packagers easier. + +* Fix #291143 by including man pages contributed by Stephan Peijnik from the + Debian project. + +* Fix #358202, effectively a race condition, by properly synchronizing file + creation at cluster startup time. + +* `%timeit` now handles correctly functions that take a long time to execute + even the first time, by not repeating them. + +* Fix #239054, releasing of references after exiting. + +* Fix #341726, thanks to Alexander Clausen. + +* Fix #269966. This long-standing and very difficult bug (which is actually a + problem in Python itself) meant long-running sessions would inevitably grow + in memory size, often with catastrophic consequences if users had large + objects in their scripts. Now, using `%run` repeatedly should not cause any + memory leaks. Special thanks to John Hunter and Sameer D'Costa for their + help with this bug. + +* Fix #295371, bug in `%history`. + +* Improved support for py2exe. + +* Fix #270856: IPython hangs with PyGTK + +* Fix #270998: A magic with no docstring breaks the '%magic magic' + +* fix #271684: -c startup commands screw up raw vs. native history + +* Numerous bugs on Windows with the new ipcluster have been fixed. + +* The ipengine and ipcontroller scripts now handle missing furl files + more gracefully by giving better error messages. + +* %rehashx: Aliases no longer contain dots. python3.0 binary + will create alias python30. Fixes: + #259716 "commands with dots in them don't work" + +* %cpaste: %cpaste -r repeats the last pasted block. + The block is assigned to pasted_block even if code + raises exception. + +* Bug #274067 'The code in get_home_dir is broken for py2exe' was + fixed. + +* Many other small bug fixes not listed here by number (see the bzr log for + more info). + +Backwards incompatible changes +------------------------------ + +* `ipykit` and related files were unmaintained and have been removed. + +* The :func:`IPython.genutils.doctest_reload` does not actually call + `reload(doctest)` anymore, as this was causing many problems with the test + suite. It still resets `doctest.master` to None. + +* While we have not deliberately broken Python 2.4 compatibility, only minor + testing was done with Python 2.4, while 2.5 and 2.6 were fully tested. But + if you encounter problems with 2.4, please do report them as bugs. + +* The :command:`ipcluster` now requires a mode argument; for example to start a + cluster on the local machine with 4 engines, you must now type:: + + $ ipcluster local -n 4 + +* The controller now has a ``-r`` flag that needs to be used if you want to + reuse existing furl files. Otherwise they are deleted (the default). + +* Remove ipy_leo.py. You can use :command:`easy_install ipython-extension` to + get it. (done to decouple it from ipython release cycle) + diff --git a/docs/source/whatsnew/version0.8.txt b/docs/source/whatsnew/version0.8.txt new file mode 100644 index 0000000..38d5ed0 --- /dev/null +++ b/docs/source/whatsnew/version0.8.txt @@ -0,0 +1,34 @@ +======================================== +0.8 series +======================================== + +Release 0.8.4 +============= + +This was a quick release to fix an unfortunate bug that slipped into the 0.8.3 +release. The ``--twisted`` option was disabled, as it turned out to be broken +across several platforms. + + +Release 0.8.3 +============= + +* pydb is now disabled by default (due to %run -d problems). You can enable + it by passing -pydb command line argument to IPython. Note that setting + it in config file won't work. + + +Release 0.8.2 +============= + +* %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory + and jumps to /foo. The current behaviour is closer to the documented + behaviour, and should not trip anyone. + + +Older releases +============== + +Changes in earlier releases of IPython are described in the older file +``ChangeLog``. Please refer to this document for details. + diff --git a/docs/source/whatsnew/version0.9.txt b/docs/source/whatsnew/version0.9.txt new file mode 100644 index 0000000..5887c5e --- /dev/null +++ b/docs/source/whatsnew/version0.9.txt @@ -0,0 +1,283 @@ +======================================== +0.9 series +======================================== + +Release 0.9.1 +============= + +This release was quickly made to restore compatibility with Python 2.4, which +version 0.9 accidentally broke. No new features were introduced, other than +some additional testing support for internal use. + + +Release 0.9 +=========== + +New features +------------ + +* All furl files and security certificates are now put in a read-only + directory named ~./ipython/security. + +* A single function :func:`get_ipython_dir`, in :mod:`IPython.genutils` that + determines the user's IPython directory in a robust manner. + +* Laurent's WX application has been given a top-level script called + ipython-wx, and it has received numerous fixes. We expect this code to be + architecturally better integrated with Gael's WX 'ipython widget' over the + next few releases. + +* The Editor synchronization work by Vivian De Smedt has been merged in. This + code adds a number of new editor hooks to synchronize with editors under + Windows. + +* A new, still experimental but highly functional, WX shell by Gael Varoquaux. + This work was sponsored by Enthought, and while it's still very new, it is + based on a more cleanly organized arhictecture of the various IPython + components. We will continue to develop this over the next few releases as a + model for GUI components that use IPython. + +* Another GUI frontend, Cocoa based (Cocoa is the OSX native GUI framework), + authored by Barry Wark. Currently the WX and the Cocoa ones have slightly + different internal organizations, but the whole team is working on finding + what the right abstraction points are for a unified codebase. + +* As part of the frontend work, Barry Wark also implemented an experimental + event notification system that various ipython components can use. In the + next release the implications and use patterns of this system regarding the + various GUI options will be worked out. + +* IPython finally has a full test system, that can test docstrings with + IPython-specific functionality. There are still a few pieces missing for it + to be widely accessible to all users (so they can run the test suite at any + time and report problems), but it now works for the developers. We are + working hard on continuing to improve it, as this was probably IPython's + major Achilles heel (the lack of proper test coverage made it effectively + impossible to do large-scale refactoring). The full test suite can now + be run using the :command:`iptest` command line program. + +* The notion of a task has been completely reworked. An `ITask` interface has + been created. This interface defines the methods that tasks need to + implement. These methods are now responsible for things like submitting + tasks and processing results. There are two basic task types: + :class:`IPython.kernel.task.StringTask` (this is the old `Task` object, but + renamed) and the new :class:`IPython.kernel.task.MapTask`, which is based on + a function. + +* A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to + standardize the idea of a `map` method. This interface has a single `map` + method that has the same syntax as the built-in `map`. We have also defined + a `mapper` factory interface that creates objects that implement + :class:`IPython.kernel.mapper.IMapper` for different controllers. Both the + multiengine and task controller now have mapping capabilties. + +* The parallel function capabilities have been reworks. The major changes are + that i) there is now an `@parallel` magic that creates parallel functions, + ii) the syntax for mulitple variable follows that of `map`, iii) both the + multiengine and task controller now have a parallel function implementation. + +* All of the parallel computing capabilities from `ipython1-dev` have been + merged into IPython proper. This resulted in the following new subpackages: + :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`, + :mod:`IPython.tools` and :mod:`IPython.testing`. + +* As part of merging in the `ipython1-dev` stuff, the `setup.py` script and + friends have been completely refactored. Now we are checking for + dependencies using the approach that matplotlib uses. + +* The documentation has been completely reorganized to accept the + documentation from `ipython1-dev`. + +* We have switched to using Foolscap for all of our network protocols in + :mod:`IPython.kernel`. This gives us secure connections that are both + encrypted and authenticated. + +* We have a brand new `COPYING.txt` files that describes the IPython license + and copyright. The biggest change is that we are putting "The IPython + Development Team" as the copyright holder. We give more details about + exactly what this means in this file. All developer should read this and use + the new banner in all IPython source code files. + +* sh profile: ./foo runs foo as system command, no need to do !./foo anymore + +* String lists now support ``sort(field, nums = True)`` method (to easily sort + system command output). Try it with ``a = !ls -l ; a.sort(1, nums=1)``. + +* '%cpaste foo' now assigns the pasted block as string list, instead of string + +* The ipcluster script now run by default with no security. This is done + because the main usage of the script is for starting things on localhost. + Eventually when ipcluster is able to start things on other hosts, we will put + security back. + +* 'cd --foo' searches directory history for string foo, and jumps to that dir. + Last part of dir name is checked first. If no matches for that are found, + look at the whole path. + + +Bug fixes +--------- + +* The Windows installer has been fixed. Now all IPython scripts have ``.bat`` + versions created. Also, the Start Menu shortcuts have been updated. + +* The colors escapes in the multiengine client are now turned off on win32 as + they don't print correctly. + +* The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing + mpi_import_statement incorrectly, which was leading the engine to crash when + mpi was enabled. + +* A few subpackages had missing ``__init__.py`` files. + +* The documentation is only created if Sphinx is found. Previously, the + ``setup.py`` script would fail if it was missing. + +* Greedy ``cd`` completion has been disabled again (it was enabled in 0.8.4) as + it caused problems on certain platforms. + + +Backwards incompatible changes +------------------------------ + +* The ``clusterfile`` options of the :command:`ipcluster` command has been + removed as it was not working and it will be replaced soon by something much + more robust. + +* The :mod:`IPython.kernel` configuration now properly find the user's + IPython directory. + +* In ipapi, the :func:`make_user_ns` function has been replaced with + :func:`make_user_namespaces`, to support dict subclasses in namespace + creation. + +* :class:`IPython.kernel.client.Task` has been renamed + :class:`IPython.kernel.client.StringTask` to make way for new task types. + +* The keyword argument `style` has been renamed `dist` in `scatter`, `gather` + and `map`. + +* Renamed the values that the rename `dist` keyword argument can have from + `'basic'` to `'b'`. + +* IPython has a larger set of dependencies if you want all of its capabilities. + See the `setup.py` script for details. + +* The constructors for :class:`IPython.kernel.client.MultiEngineClient` and + :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple. + Instead they take the filename of a file that contains the FURL for that + client. If the FURL file is in your IPYTHONDIR, it will be found automatically + and the constructor can be left empty. + +* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created + using the factory functions :func:`get_multiengine_client` and + :func:`get_task_client`. These return a `Deferred` to the actual client. + +* The command line options to `ipcontroller` and `ipengine` have changed to + reflect the new Foolscap network protocol and the FURL files. Please see the + help for these scripts for details. + +* The configuration files for the kernel have changed because of the Foolscap + stuff. If you were using custom config files before, you should delete them + and regenerate new ones. + +Changes merged in from IPython1 +------------------------------- + +New features +............ + +* Much improved ``setup.py`` and ``setupegg.py`` scripts. Because Twisted and + zope.interface are now easy installable, we can declare them as dependencies + in our setupegg.py script. + +* IPython is now compatible with Twisted 2.5.0 and 8.x. + +* Added a new example of how to use :mod:`ipython1.kernel.asynclient`. + +* Initial draft of a process daemon in :mod:`ipython1.daemon`. This has not + been merged into IPython and is still in `ipython1-dev`. + +* The ``TaskController`` now has methods for getting the queue status. + +* The ``TaskResult`` objects not have information about how long the task + took to run. + +* We are attaching additional attributes to exceptions ``(_ipython_*)`` that + we use to carry additional info around. + +* New top-level module :mod:`asyncclient` that has asynchronous versions (that + return deferreds) of the client classes. This is designed to users who want + to run their own Twisted reactor. + +* All the clients in :mod:`client` are now based on Twisted. This is done by + running the Twisted reactor in a separate thread and using the + :func:`blockingCallFromThread` function that is in recent versions of Twisted. + +* Functions can now be pushed/pulled to/from engines using + :meth:`MultiEngineClient.push_function` and + :meth:`MultiEngineClient.pull_function`. + +* Gather/scatter are now implemented in the client to reduce the work load + of the controller and improve performance. + +* Complete rewrite of the IPython docuementation. All of the documentation + from the IPython website has been moved into docs/source as restructured + text documents. PDF and HTML documentation are being generated using + Sphinx. + +* New developer oriented documentation: development guidelines and roadmap. + +* Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt`` + file that is organized by release and is meant to provide something more + relevant for users. + +Bug fixes +......... + +* Created a proper ``MANIFEST.in`` file to create source distributions. + +* Fixed a bug in the ``MultiEngine`` interface. Previously, multi-engine + actions were being collected with a :class:`DeferredList` with + ``fireononeerrback=1``. This meant that methods were returning + before all engines had given their results. This was causing extremely odd + bugs in certain cases. To fix this problem, we have 1) set + ``fireononeerrback=0`` to make sure all results (or exceptions) are in + before returning and 2) introduced a :exc:`CompositeError` exception + that wraps all of the engine exceptions. This is a huge change as it means + that users will have to catch :exc:`CompositeError` rather than the actual + exception. + +Backwards incompatible changes +.............................. + +* All names have been renamed to conform to the lowercase_with_underscore + convention. This will require users to change references to all names like + ``queueStatus`` to ``queue_status``. + +* Previously, methods like :meth:`MultiEngineClient.push` and + :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``. This was + becoming a problem as we weren't able to introduce new keyword arguments into + the API. Now these methods simple take a dict or sequence. This has also + allowed us to get rid of the ``*All`` methods like :meth:`pushAll` and + :meth:`pullAll`. These things are now handled with the ``targets`` keyword + argument that defaults to ``'all'``. + +* The :attr:`MultiEngineClient.magicTargets` has been renamed to + :attr:`MultiEngineClient.targets`. + +* All methods in the MultiEngine interface now accept the optional keyword + argument ``block``. + +* Renamed :class:`RemoteController` to :class:`MultiEngineClient` and + :class:`TaskController` to :class:`TaskClient`. + +* Renamed the top-level module from :mod:`api` to :mod:`client`. + +* Most methods in the multiengine interface now raise a :exc:`CompositeError` + exception that wraps the user's exceptions, rather than just raising the raw + user's exception. + +* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` + and ``pull``. + diff --git a/docs/sphinxext/apigen.py b/docs/sphinxext/apigen.py index afce9da..1237409 100644 --- a/docs/sphinxext/apigen.py +++ b/docs/sphinxext/apigen.py @@ -251,6 +251,7 @@ class ApiDocWriter(object): ad += ' :members:\n' \ ' :undoc-members:\n' \ ' :show-inheritance:\n' \ + ' :inherited-members:\n' \ '\n' \ ' .. automethod:: __init__\n' if multi_fx: diff --git a/docs/sphinxext/ipython_console_highlighting.py b/docs/sphinxext/ipython_console_highlighting.py index 00f9abd..217b779 100644 --- a/docs/sphinxext/ipython_console_highlighting.py +++ b/docs/sphinxext/ipython_console_highlighting.py @@ -1,4 +1,8 @@ """reST directive for syntax-highlighting ipython interactive sessions. + +XXX - See what improvements can be made based on the new (as of Sept 2009) +'pycon' lexer for the python console. At the very least it will give better +highlighted tracebacks. """ #----------------------------------------------------------------------------- @@ -15,7 +19,6 @@ from pygments.token import Comment, Generic from sphinx import highlighting - #----------------------------------------------------------------------------- # Global constants line_re = re.compile('.*?\n') @@ -77,8 +80,11 @@ class IPythonConsoleLexer(Lexer): [(0, Generic.Prompt, continue_prompt.group())])) curcode += line[continue_prompt.end():] elif output_prompt is not None: + # Use the 'error' token for output. We should probably make + # our own token, but error is typicaly in a bright color like + # red, so it works fine for our output prompts. insertions.append((len(curcode), - [(0, Generic.Output, output_prompt.group())])) + [(0, Generic.Error, output_prompt.group())])) curcode += line[output_prompt.end():] else: if curcode: @@ -93,6 +99,16 @@ class IPythonConsoleLexer(Lexer): pylexer.get_tokens_unprocessed(curcode)): yield item + +def setup(app): + """Setup as a sphinx extension.""" + + # This is only a lexer, so adding it below to pygments appears sufficient. + # But if somebody knows that the right API usage should be to do that via + # sphinx, by all means fix it here. At least having this setup.py + # suppresses the sphinx warning we'd get without it. + pass + #----------------------------------------------------------------------------- # Register the extension as a valid pygments lexer highlighting.lexers['ipython'] = IPythonConsoleLexer() diff --git a/docs/sphinxext/only_directives.py b/docs/sphinxext/only_directives.py deleted file mode 100644 index 57d70a4..0000000 --- a/docs/sphinxext/only_directives.py +++ /dev/null @@ -1,93 +0,0 @@ -# -# A pair of directives for inserting content that will only appear in -# either html or latex. -# - -from docutils.nodes import Body, Element -from docutils.writers.html4css1 import HTMLTranslator -from docutils.parsers.rst import directives - -# The sphinx API has changed, so we try both the old and new import forms -try: - from sphinx.latexwriter import LaTeXTranslator -except ImportError: - from sphinx.writers.latex import LaTeXTranslator - - -class html_only(Body, Element): - pass - -class latex_only(Body, Element): - pass - -def run(content, node_class, state, content_offset): - text = '\n'.join(content) - node = node_class(text) - state.nested_parse(content, content_offset, node) - return [node] - -try: - from docutils.parsers.rst import Directive -except ImportError: - from docutils.parsers.rst.directives import _directives - - def html_only_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return run(content, html_only, state, content_offset) - - def latex_only_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return run(content, latex_only, state, content_offset) - - for func in (html_only_directive, latex_only_directive): - func.content = 1 - func.options = {} - func.arguments = None - - _directives['htmlonly'] = html_only_directive - _directives['latexonly'] = latex_only_directive -else: - class OnlyDirective(Directive): - has_content = True - required_arguments = 0 - optional_arguments = 0 - final_argument_whitespace = True - option_spec = {} - - def run(self): - self.assert_has_content() - return run(self.content, self.node_class, - self.state, self.content_offset) - - class HtmlOnlyDirective(OnlyDirective): - node_class = html_only - - class LatexOnlyDirective(OnlyDirective): - node_class = latex_only - - directives.register_directive('htmlonly', HtmlOnlyDirective) - directives.register_directive('latexonly', LatexOnlyDirective) - -def setup(app): - app.add_node(html_only) - app.add_node(latex_only) - - # Add visit/depart methods to HTML-Translator: - def visit_perform(self, node): - pass - def depart_perform(self, node): - pass - def visit_ignore(self, node): - node.children = [] - def depart_ignore(self, node): - node.children = [] - - HTMLTranslator.visit_html_only = visit_perform - HTMLTranslator.depart_html_only = depart_perform - HTMLTranslator.visit_latex_only = visit_ignore - HTMLTranslator.depart_latex_only = depart_ignore - - LaTeXTranslator.visit_html_only = visit_ignore - LaTeXTranslator.depart_html_only = depart_ignore - LaTeXTranslator.visit_latex_only = visit_perform - LaTeXTranslator.depart_latex_only = depart_perform diff --git a/docs/sphinxext/plot_directive.py b/docs/sphinxext/plot_directive.py deleted file mode 100644 index a1a0621..0000000 --- a/docs/sphinxext/plot_directive.py +++ /dev/null @@ -1,155 +0,0 @@ -"""A special directive for including a matplotlib plot. - -Given a path to a .py file, it includes the source code inline, then: - -- On HTML, will include a .png with a link to a high-res .png. - -- On LaTeX, will include a .pdf - -This directive supports all of the options of the `image` directive, -except for `target` (since plot will add its own target). - -Additionally, if the :include-source: option is provided, the literal -source will be included inline, as well as a link to the source. -""" - -import sys, os, glob, shutil -from docutils.parsers.rst import directives - -try: - # docutils 0.4 - from docutils.parsers.rst.directives.images import align -except ImportError: - # docutils 0.5 - from docutils.parsers.rst.directives.images import Image - align = Image.align - - -import matplotlib -import IPython.Shell -matplotlib.use('Agg') -import matplotlib.pyplot as plt - -mplshell = IPython.Shell.MatplotlibShell('mpl') - -options = {'alt': directives.unchanged, - 'height': directives.length_or_unitless, - 'width': directives.length_or_percentage_or_unitless, - 'scale': directives.nonnegative_int, - 'align': align, - 'class': directives.class_option, - 'include-source': directives.flag } - -template = """ -.. htmlonly:: - - [`source code <../%(srcdir)s/%(basename)s.py>`__, - `png <../%(srcdir)s/%(basename)s.hires.png>`__, - `pdf <../%(srcdir)s/%(basename)s.pdf>`__] - - .. image:: ../%(srcdir)s/%(basename)s.png -%(options)s - -.. latexonly:: - .. image:: ../%(srcdir)s/%(basename)s.pdf -%(options)s - -""" - -def makefig(fullpath, outdir): - """ - run a pyplot script and save the low and high res PNGs and a PDF in _static - """ - - fullpath = str(fullpath) # todo, why is unicode breaking this - formats = [('png', 100), - ('hires.png', 200), - ('pdf', 72), - ] - - basedir, fname = os.path.split(fullpath) - basename, ext = os.path.splitext(fname) - all_exists = True - - if basedir != outdir: - shutil.copyfile(fullpath, os.path.join(outdir, fname)) - - for format, dpi in formats: - outname = os.path.join(outdir, '%s.%s' % (basename, format)) - if not os.path.exists(outname): - all_exists = False - break - - if all_exists: - print ' already have %s'%fullpath - return - - print ' building %s'%fullpath - plt.close('all') # we need to clear between runs - matplotlib.rcdefaults() - - mplshell.magic_run(fullpath) - for format, dpi in formats: - outname = os.path.join(outdir, '%s.%s' % (basename, format)) - if os.path.exists(outname): continue - plt.savefig(outname, dpi=dpi) - -def run(arguments, options, state_machine, lineno): - reference = directives.uri(arguments[0]) - basedir, fname = os.path.split(reference) - basename, ext = os.path.splitext(fname) - - # todo - should we be using the _static dir for the outdir, I am - # not sure we want to corrupt that dir with autogenerated files - # since it also has permanent files in it which makes it difficult - # to clean (save an rm -rf followed by and svn up) - srcdir = 'pyplots' - - makefig(os.path.join(srcdir, reference), srcdir) - - # todo: it is not great design to assume the makefile is putting - # the figs into the right place, so we may want to do that here instead. - - if options.has_key('include-source'): - lines = ['.. literalinclude:: ../pyplots/%(reference)s' % locals()] - del options['include-source'] - else: - lines = [] - - options = [' :%s: %s' % (key, val) for key, val in - options.items()] - options = "\n".join(options) - - lines.extend((template % locals()).split('\n')) - - state_machine.insert_input( - lines, state_machine.input_lines.source(0)) - return [] - - -try: - from docutils.parsers.rst import Directive -except ImportError: - from docutils.parsers.rst.directives import _directives - - def plot_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return run(arguments, options, state_machine, lineno) - plot_directive.__doc__ = __doc__ - plot_directive.arguments = (1, 0, 1) - plot_directive.options = options - - _directives['plot'] = plot_directive -else: - class plot_directive(Directive): - required_arguments = 1 - optional_arguments = 0 - final_argument_whitespace = True - option_spec = options - def run(self): - return run(self.arguments, self.options, - self.state_machine, self.lineno) - plot_directive.__doc__ = __doc__ - - directives.register_directive('plot', plot_directive) -