5.15 pisces.spkilib.sexp - Support routines from S-expressions

5.15 `pisces.spkilib.sexp` - Support routines from S-expressions

This module defines public functions for manipulating S-expressions, and a collection of helper functions that are used by by other modules in pisces.spkilib to create S-expressions for standard SPKI objects.

The SPKI structure draft [1] defines a canonical S-expression as follows:

``All SPKI structures communicated from one machine to another must be in canonical form. If canonical S-expressions need to be transmitted over a 7-bit channel, there is a form defined for base64 encoding them.

``A canonical S-expression is formed from binary byte strings, each prefixed by its length, plus the punctuation characters ()[]. The length of a byte string is a non-negative ASCII decimal number, with no unnecessary leading 0 digits, terminated by :. The canonical form is a unique representation of an S-expression and is used as the input to all hash and signature functions.''

parse (buf): Parse the S-expression buf encoded in canonical form or in base64. Returns a SExp instance or raises ParseError. Can raise ParseError.

parseText (buf): Parse a human-readable version of an S-expression buf. The human-readable form is roughly equivalent to the advanced form described in the struction document [1], but has some significant shortcomings. It is not possible to use parseText to parse an S-expression that includes multi-line base64 output. It is most useful for parsing simple S-expressions entered by users on a command line.

construct (elts): Construct an S-expression from the Python sequence elts. Each element of elts must be a string or another sequence.

SExp ([canon], [repr])

The SExp class represents S-expressions. Instances behave like sequences, allowing you to access element n of the S-expression using sx[n].

The constructor takes takes a single keyword argument. It must be either canon, a string containing the canonical representation of the S-expression, or repr, a Python sequence representing the S-expression. These two constructor forms are equivalent to calling the functions parse and construct below. User code will be clearer if these functions are called.

The __str__ method, called by str and print, converts the S-expression to a human-readable form. The pretty-printer is not ideal, but it is better than nothing.

encode_base64 (): Return a string containing the base64 encoding of the S-expression.

encode_canonical (): Return a string containing the canonical encoding of the S-expression.

ParseError: A ParseError is raised when parse is called with invalid data. The exception object contains three attributes: exp, the data expected, got, the data actually found, and ref, the encoded data that contained the error. The ref attribute may be None.