Developer Guidelines for the chainsaw branch

Software Architecture Guidelines

This section covers general design ideas about the software architecture of IPython that are not covered elsewhere. There are many different aspects/components of IPython. In the current version of IPython, all these components are tightly coupled together, so that none of the components can be used, replaced or modified without considerable pain. We see this as a significant problem and one of the main goals in refactoring IPython is to move towards components that are much more independent and loosly coupled. This will allow components to be

• Assembled in interesting new ways.
• Replaced for customization purposes.
• Tested independently.

Here are some general guidelines:

• Components should talk to each other through well defined interfaces.
• The core functionaliry of IPython should be encapsulated components that know nothing about i) networking protocols ii) GUI/terminal display and event handling. That is, IPython should be a library, not an application.
• The core functionality should, wherever possible be broken into semi-independent components that can be loosly coupled together.
• All networkng issues should be completely hidden from the core components.
• The design must allow for interprocess communication to happen over many different network protocols and perhaps simultaneously. That is, the core components must not assume that one particular network protocol will be used.
• Extreme care must be used when determining which components are synchronous and which are asynchronous. The usual rule is that whenever Twisted is involved, everything should be asynchrounous. But this does not work for us - we must allow for blocking/synchronous operations at certain levels. An example is if extension code is run in a Twisted managed process that does not release the GIL.
• It is possible that both message and RPC oriented network protocols will be appropriate in different contexts. Our design must allow for this.
• Adaptors should be used to connect incompatible components.

Twisted Architecture

Because IPython is being built with Twisted, the architecture of IPython will inherit many of the design patterns of Twisted. Some of the important patterns/classes in Twisted.

service

In Twisted a service is used to encapsulate the main functionality of an application that does not depend on networking. Thus, the IPython Core should be available as a Twisted service. But, because we want to be able to use IPython as a library without Twisted, the IPython Core at the lowest level should be written as a standard python class. Then we will wrap that class into a service for use within Twisted. Because the IPython Core will not depend on Twisted in any way, it will be fully synchronous. The wrapping of the IPython Core into a Twisted service could change this so that methods return deferreds.

Notes

• Look into py.test for testing. I hate unittest. RTK: TestGears uses a similar style for test organization (i.e. primarily just a bunch of functions rather than TestCase?'s and TestSuite?'s) but it can actually interoperate with tools that are expecting unittest.py TestSuite?'s. py.test has some other features (like suppressing stderr/stdout unless the test fails) that might be desired.