| 1 | | User visible changes in Foolscap (aka newpb/pb2). |
|---|
| | 1 | User visible changes in Foolscap (aka newpb/pb2). -*- outline -*- |
|---|
| | 2 | |
|---|
| | 3 | * Release 0.0.6 (18 Dec 2006) |
|---|
| | 4 | |
|---|
| | 5 | ** INCOMPATIBLE PROTOCOL CHANGES |
|---|
| | 6 | |
|---|
| | 7 | Version 0.0.6 will not interoperate with versions 0.0.5 or earlier, because |
|---|
| | 8 | of changes to the negotiation process and the method-calling portion of the |
|---|
| | 9 | main wire protocol. (you were warned :-). There are still more incompatible |
|---|
| | 10 | changes to come in future versions as the feature set and protocol |
|---|
| | 11 | stabilizes. Make sure you can upgrade both ends of the wire until a protocol |
|---|
| | 12 | freeze has been declared. |
|---|
| | 13 | |
|---|
| | 14 | *** Negotiation versions now specify a range, instead of a single number |
|---|
| | 15 | |
|---|
| | 16 | The two ends of a connection will agree to use the highest mutually-supported |
|---|
| | 17 | version. This approach should make it much easier to maintain backwards |
|---|
| | 18 | compatibility in the future. |
|---|
| | 19 | |
|---|
| | 20 | *** Negotiation now includes an initial VOCAB table |
|---|
| | 21 | |
|---|
| | 22 | One of the outputs of connection negotiation is the initial table of VOCAB |
|---|
| | 23 | tokens to use for abbreviating commonly-used strings into short tokens |
|---|
| | 24 | (usually just 2 bytes). Both ends have the ability to modify this table at any |
|---|
| | 25 | time, but by setting the initial table during negotiation we same some |
|---|
| | 26 | protocol traffic. VOCAB-izing common strings (like 'list' and 'dict') have |
|---|
| | 27 | the potential to compress wire traffic by maybe 50%. |
|---|
| | 28 | |
|---|
| | 29 | *** remote methods now accept both positional and keyword arguments |
|---|
| | 30 | |
|---|
| | 31 | Previously you had to use a RemoteInterface specification to be able to pass |
|---|
| | 32 | positional arguments into callRemote(). (the RemoteInterface schema was used |
|---|
| | 33 | to convert the positional arguments into keyword arguments before sending |
|---|
| | 34 | them over the wire). In 0.0.6 you can pass both posargs and kwargs over the |
|---|
| | 35 | wire, and the remote end will pass them directly to the target method. When |
|---|
| | 36 | schemas are in effect, the arguments you send will be mapped to the method's |
|---|
| | 37 | named parameters in the same left-to-right way that python does it. This |
|---|
| | 38 | should make it easier to port oldpb code to use Foolscap, since you don't |
|---|
| | 39 | have to rewrite everything to use kwargs exclusively. |
|---|
| | 40 | |
|---|
| | 41 | ** Schemas now allow =None and =RIFoo |
|---|
| | 42 | |
|---|
| | 43 | You can use 'None' in a method schema to indicate that the argument or return |
|---|
| | 44 | value must be None. This is useful for methods that always return None. You |
|---|
| | 45 | can also require that the argument be a RemoteReference that provides a |
|---|
| | 46 | particular RemoteInterface. For example: |
|---|
| | 47 | |
|---|
| | 48 | class RIUser(RemoteInterface): |
|---|
| | 49 | def get_age(): |
|---|
| | 50 | return int |
|---|
| | 51 | def delete(): |
|---|
| | 52 | return None |
|---|
| | 53 | |
|---|
| | 54 | class RIUserDatabase(RemoteInterface): |
|---|
| | 55 | def get_user(username=str): |
|---|
| | 56 | return RIUser |
|---|
| | 57 | |
|---|
| | 58 | Note that these remote interface specifications are parsed at import time, so |
|---|
| | 59 | any names they refer to must be defined before they get used (hence placing |
|---|
| | 60 | RIUserDatabase before RIUser would fail). Hopefully we'll figure out a way to |
|---|
| | 61 | fix this in the future. |
|---|
| | 62 | |
|---|
| | 63 | ** Violations are now annotated better, might keep more stack-trace information |
|---|
| | 64 | |
|---|
| | 65 | ** Copyable improvements |
|---|
| | 66 | |
|---|
| | 67 | The Copyable documentation has been split out to docs/copyable.xhtml and |
|---|
| | 68 | somewhat expanded. |
|---|
| | 69 | |
|---|
| | 70 | The new preferred Copyable usage is to have a class-level attribute named |
|---|
| | 71 | "typeToCopy" which holds the unique string. This must match the class-level |
|---|
| | 72 | "copytype" attribute of the corresponding RemoteCopy class. Copyable |
|---|
| | 73 | subclasses (or ICopyable adapters) may still implement getTypeToCopy(), but |
|---|
| | 74 | the default just returns self.typeToCopy . Most significantly, we no longer |
|---|
| | 75 | automatically use the fully-qualified classname: instead we *require* that |
|---|
| | 76 | the class definition include "typeToCopy". Feel free to use any stable and |
|---|
| | 77 | globally-unique string here, like a URI in a namespace that you control, or |
|---|
| | 78 | the fully-qualified package/module/classname of the Copyable subclass. |
|---|
| | 79 | |
|---|
| | 80 | The RemoteCopy subclass must set the 'copytype' attribute, as it is used for |
|---|
| | 81 | auto-registration. These can set copytype=None to inhibit auto-registration. |
|---|
| | 82 | |
|---|
