1# Foolscap 2 3[![PyPI](http://img.shields.io/pypi/v/foolscap.svg)](https://pypi.python.org/pypi/foolscap) 4[![Build Status](https://travis-ci.org/warner/foolscap.svg?branch=master)](https://travis-ci.org/warner/foolscap) 5 6Foolscap is an RPC/RMI (Remote Procedure Call / Remote Method Invocation) 7protocol for use with Twisted, derived/inspired by Twisted's built-in 8"Perspective Broker" package. 9 10If you have control of both ends of the wire, and are thus not constrained to 11use some other protocol like HTTP/XMLRPC/CORBA/etc, you might consider using 12Foolscap. 13 14Fundamentally, Foolscap allows you to make a python object in one process 15available to code in other processes, which means you can invoke its methods 16remotely. This includes a data serialization layer to convey the object 17graphs for the arguments and the eventual response, and an object reference 18system to keep track of which objects you are connecting to. It uses a 19capability-based security model, such that once you create a non-public 20object, it is only accessible to clients to whom you've given the 21(unguessable) FURL. You can of course publish world-visible objects that 22have well-known FURLs. 23 24Full documentation and examples are in the doc/ directory. 25 26## DEPENDENCIES 27 28* Python 3.5 or higher (still works under Python 2.7 for now) 29* Twisted 16.0.0 or later 30* PyOpenSSL (tested against 16.0.0) 31 32 33## INSTALLATION 34 35To install foolscap into your system's normal python library directory, just 36run the following (you will probably have to do this as root): 37 38``` 39pip install . 40``` 41 42You can also just add the foolscap source tree to your PYTHONPATH, since 43there are no compile steps or .so/.dll files involved. 44 45 46## COMPATIBILITY 47 48Foolscap's wire protocol is unlikely to change in the near future. 49 50Foolscap has a built-in version-negotiation mechanism that allows the two 51processes to determine how to best communicate with each other. The two ends 52will agree upon the highest mutually-supported version for all their 53traffic. If they do not have any versions in common, the connection will 54fail with a NegotiationError. 55 56Please check the NEWS file for announcements of compatibility-breaking 57changes in any given release. 58 59As of Foolscap-0.14.0, this library is mostly compatible with Python 3 60(specifically 3.5 or higher), and is tested against 3.5, 3.6, 3.7, and 3.8. 61It will retain compatibility with Python 2.7 for a little while longer, to 62ease the transition, but since Python 2 was marked End-Of-Life in January 632020, this compatibility will not be maintained forever. 64 65 66## HISTORY 67 68Foolscap is a rewrite of the Perspective Broker protocol provided by Twisted 69(in the twisted.pb package), with the goal of improving serialization 70flexibility and connection security. It also adds features to assist 71application development, such as distributed/incident-triggered logging, 72Service management, persistent object naming, and debugging tools. 73 74For a brief while, it was intended to replace Perspective Broker, so it had 75a name of "newpb" or "pb2". However we no longer expect Foolscap to ever be 76added to the Twisted source tree. 77 78A "foolscap" is a size of paper, probably measuring 17 by 13.5 inches. A 79twisted foolscap of paper makes a good fool's cap. Also, "cap" implies 80capabilities, and Foolscap is a protocol to implement a distributed 81object-capabilities model in python. 82 83## AUTHOR 84 85Brian Warner is responsible for this thing. Please discuss it on the 86twisted-python mailing list. 87 88The Foolscap home page is a Trac instance at 89<http://foolscap.lothar.com/trac>. It contains pointers to the latest 90release, bug reports, patches, documentation, and other resources. 91 92Foolscap is distributed under the same license as Twisted itself, namely the 93MIT license. Details are in the LICENSE file. 94 95