root/README

                                 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.