1. Stephan Peijnik
  2. foolscap

Overview

Foolscap

(aka newpb, aka pb2)

This is a ground-up rewrite of Perspective Broker, which itself is Twisted's native RPC/RMI protocol (Remote Procedure Call / Remote Method Invocation). If you have control of both ends of the wire, and are thus not constrained to use some other protocol like HTTP/XMLRPC/CORBA/etc, you might consider using Foolscap.

Fundamentally, Foolscap allows you to make a python object in one process available to code in other processes, which means you can invoke its methods remotely. This includes a data serialization layer to convey the object graphs for the arguments and the eventual response, and an object reference system to keep track of which objects you are connecting to. It uses a capability-based security model, such that once you create a non-public object, it is only accessible to clients to whom you've given the (unguessable) FURL. You can of course publish world-visible objects that have well-known FURLs.

Full documentation and examples are in the doc/ directory.

DEPENDENCIES:

  • Python 2.4 or later
  • Twisted 2.4.0 or later
  • PyOpenSSL (tested against 0.6)

INSTALLATION:

To install foolscap into your system's normal python library directory, just run the following (you will probably have to do this as root):

python setup.py install

You can also just add the foolscap source tree to your PYTHONPATH, since there are no compile steps or .so/.dll files involved.

COMPATIBILITY:

Foolscap is still under development. The wire protocol is almost certainly going to change in the near future, so forward compatibility between versions is NOT yet guaranteed. Do not use Foolscap if you do not have continuing control over both ends of the wire. Foolscap is not yet suitable for widespread deployment: for production applications please continue to use oldpb (in twisted.spread).

Foolscap has a built-in version-negotiation mechanism that allows the two processes to determine how to best communicate with each other. The two ends will agree upon the highest mutually-supported version for all their traffic. If they do not have any versions in common, the connection will fail with a NegotiationError.

Certain releases of Foolscap will remain compatible with earlier releases. Please check the NEWS file for announcements of compatibility-breaking changes in any given release.

NAMING:

The established version of PB that has been around for years is referred to here as "oldpb". The new version contained in this release is known as "Foolscap", but at various points of its development was known as "newpb" or "pb2". The release tarballs are named "foolscap-x.y.z". The python module name is "foolscap" . These names are still in flux. At some point in the future, we may come up with a suitably clever and confusing name that will replace any or all of these.

A "foolscap" is a size of paper, probably measuring 17 by 13.5 inches. A twisted foolscap of paper makes a good fool's cap. Also, "cap" makes me think of capabilities, and Foolscap is a protocol to implement a distributed object-capabilities model in python.

AUTHOR:

Brian Warner is responsible for this thing. Please discuss it on the twisted-python mailing list.

The Foolscap home page is a Trac instance at <http://foolscap.lothar.com>. It contains pointers to the latest release, bug reports, patches, documentation, and other resources.

Foolscap is distributed under the same license as Twisted itself, namely the MIT license. Details are in the LICENSE file.