The Sequence class is what underlies the add_sequence() methods on MockSession and other Container classes.
Sequence instances are used to assert that API function calls must happen in a defined, concrete order (as opposed to, say, AnyOrder).
Sequence inherits from the Container and State base classes (in that order) and conforms to the protocols defined by both.
This page details only areas where Sequence extends or deviates from those protocols.
The Sequence() constructor takes a single, optional argument.
Sequence()
Sequence([state_1, state_2, ..., state_n])
If Sequence() is invoked without arguments, an empty Sequence instance will be created.
This instance must be populated manually using the add_* methods defined in the Container protocol.
If Sequence() is invoked with an argument, the passed-in object must be capable of iteration (all Containers are capable of iteration), and all elements in the iterable must be instances of the State class.
These states will be used to populate the newly-created Sequence in the order in which they are obtained from the iterator.
Sequence.__call__ conforms to the Container protocol.
When Sequence.__call__ is invoked to validate an API function call, the invocant will delegate the validation to subsequent contained states.
For example, assuming state_1 and state_2 are valid States,
seq = Sequence([state_1, state_2])
the first time seq is asked to validate an API call, it will ask state_1 to validate the call.
The second time seq is asked to validate, the resposibility will be passed on to state_2 and so on down the line.
If seq is asked to approve a third API call, it will raise an exception, complaining that it has run out of States.
Invocations of Sequence.reset cause the invocant to restart delegation with the first member state.
In the above example, after the second validation request has "used up" state_2, a call to seq.reset() would cause the next validation request to be directed to state_1.
When iterating over Container instances, the order in which State objects will be returned is the same in which they were added.