Transcript

Every sent or received line is retained in one chronological transcript:

partner.transcript
# [(timestamp, 'stdin',  'hello again'),
#  (timestamp, 'stdout', 'HELLO AGAIN')]

The stdin, stdout, and stderr properties provide filtered views of the same history. History() provides optional stream and ignored-output filters. Empty lines are preserved. A received LF and one optional preceding CR are stripped from each line.

Ignored output

Optional regex filters may be supplied with ignore at initialization time, or by assigning or mutating the ignore list later. A single string replaces the list with one filter; an iterable replaces it with multiple filters. Prefix a string with stdout:, stderr:, or all: to choose its stream scope; unprefixed filters apply to stdout:

partner = Partner( command, ignore=r'^progress: ' )
partner.ignore.append( r'stderr:^warning: transient ' )
partner.ignore = [ r'all:^debug: ', r'stdout:^progress: ' ]
partner.ignore.clear()

Matching decoded lines are omitted from replies and errors, but are retained in transcript as stdout-ignored or stderr-ignored events. The stdout and stderr properties include ignored lines by default.

Use History() for narrower views:

partner.History( 'stdout', ignored=False )  # non-ignored stdout lines
partner.History( 'stdout', ignored=True )   # ignored stdout lines
partner.History( 'stdout-ignored' )         # exact event-type filter

An ignored line does not count as a reply or an error, but if a multi-line reply or error is already being collected, it resets the interLineTimeout clock.

Text and bytes

Native strings are encoded using the configurable encoding and receive the configurable terminator (default \n) unless already terminated. On Python 3, explicit bytes input is written exactly as supplied, without encoding or an added terminator.

Protocol boundaries

LineDance deliberately assumes a request/reply protocol. The child must flush its output and terminate reply lines with \n. A command that remains alive but produces no output has no observable reply boundary and therefore waits until its timeout, if any. A timeout leaves the exchange desynchronized, so the Partner refuses subsequent requests rather than risk attributing a late reply to the wrong request.

Unsolicited output is retained but is not mistaken for a reply if it arrived before the request. Protocols with prompts lacking line terminators, request IDs, or explicit completion sentinels need a protocol-specific adapter.

LineDance is public-domain software released under CC0.