cicada.transcript module

Functionality for generating transcripts of library activity.

Use-cases include detailed debugging, logging network traffic, function tracing, and MPC-in-the-head for zero knowledge proofs. The latter case is described in

Ishai, Yuval, et al. “Zero-knowledge from secure multiparty computation.” Proceedings of the thirty-ninth annual ACM symposium on Theory of computing. 2007.

Examples of this technique appear in https://csrc.nist.gov/projects/pqc-dig-sig/round-1-additional-signatures as proposals for NIST PQC standardization.

class cicada.transcript.Code[source]

Bases: SimpleNamespace

Stores code-related metadata for use in Formatter.

class cicada.transcript.Formatter(fmt, netfmt, codefmt, codepre, codepost)[source]

Bases: object

Custom log formatter for transcription messages.

Unlike the generic logging.Formatter objects provided with Python, this class is configured with more than one format string, to handle each type of event that can be logged. In addition to the standard format fields provided by LogRecord attributes, the format strings can use the following.

For sent-message and received-message events:

  • net.arrow - message direction, relative to the player logging the event.

  • net.comm - communicator that sent / received the message.

  • net.comm.name - name of the communicator that sent / received the message.

  • net.comm.rank - rank of the player logging the event.

  • net.dir - message direction, relative to the player logging the event.

  • net.dst - rank of the player receiving the message.

  • net.other - rank of the player sending or receiving with the player logging the event.

  • net.payload - message payload contents.

  • net.src - rank of the player sending the message.

  • net.tag - message type.

  • net.verb - message direction, relative to the player logging the event.

For code events:

  • code.filename - the full path to the file containing the original statement.

  • code.first - this is the first line of generated code associated with the original statement.

  • code.last - this is the last line of generated code associated with the original statement.

  • code.lineno - line number of the file containing the original statement.

Parameters:

  • fmt (str, optional) – Format string for context records.

  • netfmt (str, optional) – Format string for sent- and received-message records.

  • codefmt (str, optional) – Format string for consistency verification records.

format(record)[source]

Formats a log record for display.

class cicada.transcript.HideCode[source]

Bases: object

Log filter that hides code records.

class cicada.transcript.HideContextMessages[source]

Bases: object

Log filter that hides context message records.

class cicada.transcript.HideReceivedMessages[source]

Bases: object

Log filter that hides network message records for received messages.

class cicada.transcript.HideSentMessages[source]

Bases: object

Log filter that hides network message records for sent messages.

class cicada.transcript.Message[source]

Bases: SimpleNamespace

Stores message-related metadata for use in Formatter.

cicada.transcript.assert_equal(lhs, rhs)[source]

Test two objects for equality.

Seamlessly handles special types such as numpy.ndarray, etc.

cicada.transcript.code_handler(handler=None, fmt=None, netfmt=None, codefmt=None, codepre=None, codepost=None, sent=False, received=False)[source]

Create a logging.Handler, configured to display consistency verification code records.

Parameters:

  • handler (logging.Handler, optional) – The handler to be configured. Defaults to a new instance of logging.StreamHandler if None.

  • fmt (str, optional) – Format string for context records.

  • netfmt (str, optional) – Format string for sent- and received-message records.

  • codefmt (str, optional) – Format string for consistency verification records.

  • codepre (str, optional) – Format string displayed before each group of consistency verification code records.

  • codepost (str, optional) – Format string displayed after each group of consistency verification code records.

  • sent (bool, optional) – Enable displaying sent-message records if True.

  • received (bool, optional) – Enable displaying received-message records if True.

cicada.transcript.log(message=None)[source]

Log general-purpose events into the transcription.

Application code should use this to incorporate high-level application context information alongside the lower-level network and consistency verification transcript contents.

cicada.transcript.net_handler(handler=None, fmt=None, netfmt=None, codefmt=None, codepre=None, codepost=None, sent=True, received=True, code=False)[source]

Create a logging.Handler, configured to display network message records.

Parameters:

  • handler (logging.Handler, optional) – The handler to be configured. Defaults to a new instance of logging.StreamHandler if None.

  • fmt (str, optional) – Format string for context records.

  • netfmt (str, optional) – Format string for sent- and received-message records.

  • codefmt (str, optional) – Format string for consistency verification records.

  • codepre (str, optional) – Format string displayed before each group of consistency verification code records.

  • codepost (str, optional) – Format string displayed after each group of consistency verification code records.

  • sent (bool, optional) – Disable displaying sent-message records if False.

  • received (bool, optional) – Disable displaying received-message records if False.

  • code (bool, optional) – Display consistency verification code records if True.

cicada.transcript.record()[source]

Enable transcription.

All transcription functionality depends on tracing function calls, so this must be called to begin transcription. The result is a context manager that can be used in with-statements.

cicada.transcript.set_handler(logger, handler)[source]

Set the handler for a logger, removing any other handlers.

Parameters: