API Documentation

Functions

wrap(stream[, unicode, window, echo, ...]) Wrap a stream to implement expect functionality.
streamexpect.wrap(stream, unicode=False, window=1024, echo=False, close_stream=True)[source]

Wrap a stream to implement expect functionality.

This function provides a convenient way to wrap any Python stream (a file-like object) or socket with an appropriate Expecter class for the stream type. The returned object adds an Expect.expect() method to the stream, while passing normal stream functions like read/recv and write/send through to the underlying stream.

Here’s an example of opening and wrapping a pair of network sockets:

import socket
import streamexpect

source, drain = socket.socketpair()
expecter = streamexpect.wrap(drain)
source.sendall(b'this is a test')
match = expecter.expect_bytes(b'test', timeout=5)

assert match is not None
Parameters:
  • stream – The stream/socket to wrap.
  • unicode (bool) – If True, the wrapper will be configured for Unicode matching, otherwise matching will be done on binary.
  • window (int) – Historical characters to buffer.
  • echo (bool) – If True, echoes received characters to stdout.
  • close_stream (bool) – If True, and the wrapper is used as a context manager, closes the stream at the end of the context manager.

Expecter Types

Expecter(stream_adapter, input_callback, ...) Base class for consuming input and waiting for a pattern to appear.
BytesExpecter(stream_adapter[, ...]) Expecter interface for searching a byte-oriented stream.
TextExpecter(stream_adapter[, ...]) Expecter interface for searching a text-oriented stream.
class streamexpect.Expecter(stream_adapter, input_callback, window, close_adapter)[source]

Base class for consuming input and waiting for a pattern to appear.

Implements the base class for Expecter types, which wrap over a StreamAdapter type and provide methods for applying a Searcher to the received data. Any attributes not part of this class are delegated to the underlying StreamAdapter type.

Parameters:
  • stream_adapter (StreamAdapter) – The StreamAdapter object to receive data from.
  • input_callback (function) – Callback function with one parameter that is called each time new data is read from the stream_adapter.
  • window (int) – Number of historical objects (bytes, characters, etc.) to buffer.
  • close_adapter (bool) – If True, and the Expecter is used as a context manager, closes the adapter at the end of the context manager.
expect(searcher, timeout)[source]

Apply searcher to underlying StreamAdapter

Parameters:
  • searcher (Searcher) – Searcher to apply to underlying stream.
  • timeout (float) – Timeout in seconds.
class streamexpect.BytesExpecter(stream_adapter, input_callback=None, window=1024, close_adapter=True)[source]

Expecter interface for searching a byte-oriented stream.

Parameters:
  • stream_adapter (StreamAdapter) – The StreamAdapter object to receive data from.
  • input_callback (function) – Callback function with one parameter that is called each time new data is read from the stream_adapter.
  • window (int) – Number of historical bytes to buffer.
expect(searcher, timeout=3)[source]

Wait for input matching searcher

Waits for input matching searcher for up to timeout seconds. If a match is found, the match result is returned (the specific type of returned result depends on the Searcher type). If no match is found within timeout seconds, raise an ExpectTimeout exception.

Parameters:
  • searcher (Searcher) – Searcher to apply to underlying stream.
  • timeout (float) – Timeout in seconds.
expect_bytes(b, timeout=3)

Wait for a match to the bytes in b to appear on the stream.

Waits for input matching the bytes b for up to timeout seconds. If a match is found, a SequenceMatch result is returned. If no match is found within timeout seconds, raise an ExpectTimeout exception.

Parameters:
  • b – The byte pattern to search for.
  • timeout (float) – Timeout in seconds.
Returns:

SequenceMatch if matched, None if no match was found.
expect_regex(pattern, timeout=3, regex_options=0)

Wait for a match to the regex in pattern to appear on the stream.

Waits for input matching the regex pattern for up to timeout seconds. If a match is found, a RegexMatch result is returned. If no match is found within timeout seconds, raise an ExpectTimeout exception.

Parameters:
  • pattern – The pattern to search for, as a single compiled regex or a string that will be processed as a regex.
  • timeout (float) – Timeout in seconds.
  • regex_options – Options passed to the regex engine.
Returns:

RegexMatch if matched, None if no match was found.
class streamexpect.TextExpecter(stream_adapter, input_callback=None, window=1024, close_adapter=True)[source]

Expecter interface for searching a text-oriented stream.

Parameters:
  • stream_adapter (StreamAdapter) – The StreamAdapter object to receive data from.
  • input_callback (function) – Callback function with one parameter that is called each time new data is read from the stream_adapter.
  • window (int) – Number of historical characters to buffer.
expect(searcher, timeout=3)[source]

Wait for input matching searcher.

Waits for input matching searcher for up to timeout seconds. If a match is found, the match result is returned (the specific type of returned result depends on the Searcher type). If no match is found within timeout seconds, raise an ExpectTimeout exception.

Parameters:
  • searcher (Searcher) – Searcher to apply to underlying stream.
  • timeout (float) – Timeout in seconds.
expect_regex(pattern, timeout=3, regex_options=0)

Wait for a match to the regex in pattern to appear on the stream.

Waits for input matching the regex pattern for up to timeout seconds. If a match is found, a RegexMatch result is returned. If no match is found within timeout seconds, raise an ExpectTimeout exception.

Parameters:
  • pattern – The pattern to search for, as a single compiled regex or a string that will be processed as a regex.
  • timeout (float) – Timeout in seconds.
  • regex_options – Options passed to the regex engine.
Returns:

RegexMatch if matched, None if no match was found.
expect_text(text, timeout=3)

Wait for a match to the text in text to appear on the stream.

Waits for input matching the text text for up to timeout seconds. If a match is found, a SequenceMatch result is returned. If no match is found within timeout seconds, raise an ExpectTimeout exception.

Parameters:
  • text – The plain-text pattern to search for.
  • timeout (float) – Timeout in seconds.
Returns:

SequenceMatch if matched, None if no match was found.

Searcher Types

Searcher Base class for searching buffers.
BytesSearcher(b) Binary/ASCII searcher.
TextSearcher(text) Plain text searcher.
RegexSearcher(pattern[, regex_options]) Regular expression searcher.
SearcherCollection(\*searchers) Collect multiple Searcher objects into one.
class streamexpect.Searcher[source]

Base class for searching buffers.

Implements the base class for Searcher types, which are used by the library to determine whether or not a particular buffer contains a match. The type of the match is determined by the Searcher implementation: it may be bytes, text, or something else entirely.

To conform to the Searcher interface, a class must implement one method search and one read-only property match_type. The buffer passed to the search method must match the type returned by the match_type property, and search must raise a TypeError if it does not. The member function _check_type() exists to provide this functionality for subclass implementations.

_check_type(value)[source]

Checks that value matches the type of this Searcher.

Checks that value matches the type of this Searcher, returning the value if it does and raising a TypeError if it does not.

Returns:value if type of value matches type of this Searcher.
Raises:TypeError – if type of value does not match the type of this Searcher
match_type

Read-only property that returns type matched by this Searcher

search(buf)[source]

Search the provided buffer for a match.

Search the provided buffer for a match. What exactly a match means is defined by the Searcher implementation. If the match is found, returns an SequenceMatch object, otherwise returns None.

Parameters:buf – Buffer to search for a match.
class streamexpect.BytesSearcher(b)[source]

Binary/ASCII searcher.

A binary/ASCII searcher. Matches when the pattern passed to the constructor is found in the input buffer.

Note that this class only operates on binary types. That means that in Python 3, it will fail on strings, as strings are Unicode by default. In Python 2 this class will fail on the Unicode type, as strings are ASCII by default.

Parameters:b – Bytes to search for. Must be a binary type (i.e. bytes)
search(buf)[source]

Search the provided buffer for matching bytes.

Search the provided buffer for matching bytes. If the match is found, returns a SequenceMatch object, otherwise returns None.

Parameters:buf – Buffer to search for a match.
Returns:SequenceMatch if matched, None if no match was found.
class streamexpect.TextSearcher(text)[source]

Plain text searcher.

A plain-text searcher. Matches when the text passed to the constructor is found in the input buffer.

Note that this class operates only on text types (i.e. Unicode) and raises a TypeError if used with binary data. Use the BytesSearcher type to search binary or ASCII text.

To make sure that modified (accented, grave, etc.) characters are matched accurately, the input text is converted to the Unicode canonical composed form before being used to match.

Parameters:text – Text to search for. Must be a text type (i.e. Unicode)
search(buf)[source]

Search the provided buffer for matching text.

Search the provided buffer for matching text. If the match is found, returns a SequenceMatch object, otherwise returns None.

Parameters:buf – Buffer to search for a match.
Returns:SequenceMatch if matched, None if no match was found.
class streamexpect.RegexSearcher(pattern, regex_options=0)[source]

Regular expression searcher.

Searches for a match in the stream that matches the provided regular expression.

This class follows the Python 3 model for dealing with binary versus text patterns, raising a TypeError if mixed binary/text is used. This means that a RegexSearcher that is instantiated with binary data will raise a TypeError if used on text, and a RegexSearcher instantiated with text will raise a TypeError on binary data.

Parameters:
  • pattern – The regex to search for, as a single compiled regex or a string that will be processed as a regex.
  • regex_options – Options passed to the regex engine.
search(buf)[source]

Search the provided buffer for a match to the object’s regex.

Search the provided buffer for a match to the object’s regex. If the match is found, returns a RegexMatch object, otherwise returns None.

Parameters:buf – Buffer to search for a match.
Returns:RegexMatch if matched, None if no match was found.
class streamexpect.SearcherCollection(*searchers)[source]

Collect multiple Searcher objects into one.

Collect multiple Searcher instances into a single Searcher instance. This is different than simply looping over a list of searchers, as this class will always find the earliest match from any of its sub-searchers (i.e. the match with the smallest index).

Note that this class requires that all of its sub-searchers have the same match_type.

Parameters:searchers – One or more Searcher implementations.
search(buf)[source]

Search the provided buffer for a match to any sub-searchers.

Search the provided buffer for a match to any of this collection’s sub-searchers. If a single matching sub-searcher is found, returns that sub-searcher’s match object. If multiple matches are found, the match with the smallest index is returned. If no matches are found, returns None.

Parameters:buf – Buffer to search for a match.
Returns:RegexMatch if matched, None if no match was found.

Match types

SequenceMatch(searcher, match, start, end) Information about a match that has a concept of ordering.
RegexMatch(searcher, match, start, end, groups) Information about a match from a regex.
class streamexpect.SequenceMatch(searcher, match, start, end)[source]

Information about a match that has a concept of ordering.

Parameters:
  • searcher (Searcher) – The Searcher that found the match
  • match – Portion of sequence that triggered the match
  • start (int) – Index of start of match
  • end (int) – Index of item directly after match
class streamexpect.RegexMatch(searcher, match, start, end, groups)[source]

Information about a match from a regex.

Parameters:
  • searcher (Searcher) – The Searcher that found the match
  • match – Portion of sequence that triggered the match
  • start (int) – Index of start of match
  • end (int) – Index of item directly after match
  • groups (tuple) – Contains the matched subgroups if the regex contained groups, otherwise None

StreamAdapter Types

StreamAdapter(stream) Adapter to match varying stream objects to a single interface.
PollingStreamAdapter(stream[, poll_period, ...]) A StreamAdapter that polls a non-blocking stream.
PollingSocketStreamAdapter(sock[, ...]) A StreamAdapter that polls a non-blocking socket.
PollingStreamAdapterMixin Add poll_period and max_read properties to a StreamAdapter
class streamexpect.StreamAdapter(stream)[source]

Adapter to match varying stream objects to a single interface.

Despite the existence of the Python stream interface and file-like objects, there are actually a number of subtly different implementations of streams within Python. In addition, there are stream-like constructs like sockets that use a different interface entirely (send/recv versus read/write).

This class provides a base adapter that can be used to convert anything even remotely stream-like into a form that can consistently be used by implementations of Expecter. The key method is poll(), which must always provide a blocking interface to the underlying stream, and must also provide a reliable timeout mechanism. The exact method to achieve these two goals is implementation dependent, and a particular implementation may be used to meet the need at hand.

This class also automatically delegates any non-existent attributes to the underlying stream object. This allows the adapter to be used identically to the stream.

Parameters:stream – Stream object to wrap over.
poll(timeout)[source]

Unified blocking read access to the underlying stream.

All subclasses of StreamAdapter must implement this method. Once called, the method must either:

  • Return new read data whenever it becomes available, or
  • Raise an ExpectTimeout exception if timeout is exceeded.

The amount of data to return from each call is implementation dependent, but it is important that either all data is returned from the function, or that the data be somehow returned to the stream. In other words, any data not returned must still be available the next time the poll method is called.

Note that there is no “wait forever” functionality: either some new data must be returned or an exception must occur in a finite amount of time. It is also important that, if there is a timeout, the method raise the exception as soon after the timeout occurred as is reasonably possible.

class streamexpect.PollingStreamAdapter(stream, poll_period=0.1, max_read=1024)[source]

A StreamAdapter that polls a non-blocking stream.

Polls a non-blocking stream of data until new data is available or a timeout is exceeded. It is VERY IMPORTANT that the underlying stream be non-blocking.

Parameters:
  • stream – Stream to poll for data.
  • poll_period (float) – Time (in seconds) between polls of the stream.
  • max_read (int) – The maximum number of bytes/characters to read from the stream at one time.
poll(timeout)[source]
Parameters:timeout (float) – Timeout in seconds.
class streamexpect.PollingSocketStreamAdapter(sock, poll_period=0.1, max_read=1024)[source]

A StreamAdapter that polls a non-blocking socket.

Polls a non-blocking socket for data until new data is available or a timeout is exceeded.

Parameters:
  • sock – Socket to poll for data.
  • poll_period (float) – Time (in seconds) between poll of the socket.
  • max_read (int) – The maximum number of bytes/characters to read from the socket at one time.
poll(timeout)[source]
Parameters:timeout (float) – Timeout in seconds. A timeout that is less than the poll_period will still cause a single read that may take up to poll_period seconds.
class streamexpect.PollingStreamAdapterMixin[source]

Add poll_period and max_read properties to a StreamAdapter

Exceptions

ExpectTimeout Exception raised when expect call exceeds a timeout.
class streamexpect.ExpectTimeout[source]

Exception raised when expect call exceeds a timeout.