5.3.8.8 ListIterator Objects

The iterator named in the iter (5.3.8.5) attribute of the <al-for> tag is an instance of this class. By using an object to iterate over the sequence the toolkit is able to provide additional data that is useful in formatting HTML.

The iterator will retrieve each value from the sequence exactly once. This allows you to use objects that act as sequences by implementing the Python sequence protocol. Only __getitem__() is required unless you use pagination, then __len__() is also required.

pagesize( )
Returns the pagesize that was set in the pagesize attribute.

has_prevpage( )
Returns TRUE if the page start index is greater than zero indicating that there is a previous page.

has_nextpage( )
Returns TRUE if the sequence length is greater than the page start index plus the _pagesize member indicating that there is a next page.

If the iterator has not been placed into ``page mode'' by the presence of a pagesize attribute a ListIteratorError exception will be raised.

index( )
Returns the index of the current sequence element.

start( )
Returns the index of the first sequence element on the page.

count( )
Returns the index of the current sequence element within the current page. This is equivalent to index() - start().

value( )
Returns the current sequence element.

Most of the methods and all of the members are not meant to be accessed from your code but are documented below to help clarify how the iterator behaves.

_index
Current sequence index -- returned by index().

_start
Sequence index of first element on page -- returned by start().

_count
Sequence index of current element on page -- returned by count().

_seq
Sequence being iterated over -- initialised to None and set by set_sequence().

_have_value
Indicates the state of the current element. There are three possible values: None indicates that the state is unknown and will be established when the sequence is next accessed, zero indicates that the end of sequence has been reached and there is no valid element, and one indicates the current element is valid.

_pagesize
Current page size -- initialised to 0 and set by the presence of a pagesize attribute in the <al-for> tag.

__getstate__( )
When ``page mode'' is enabled the iterator is saved into the session (via the execution context add_session_vars() method). This restricts the Python pickler to saving only the _start and _pagesize members.

__setstate__( tup)
Restores an iterator from the Python pickler.

__len__( )
When in ``page mode'' it returns the _pagesize member else it returns the length of the sequence.

set_backdoor( op, value)
The <al-input> and <al-a> tags provide nextpage and prevpage attributes that generate names using a special backdoor format. When the browser request is merged the set_value() method of the NamespaceMixin directs list backdoor input fields to this method. Refer to the documentation in section 7.6.

The value argument is the browser submitted value for the backdoor field. If a value was submitted for the backdoor field then the op argument is processed. If op equals "prevpage" or "nextpage" then the iterator selects the previous or next page respectively.

get_backdoor( op)
When generating backdoor fields for the <al-input> and <al-a> tags the toolkit calls this method to determine the value that will assigned to that field. The method returns 1.

set_pagesize( size)
Sets the _pagesize member to size.

has_sequence( )
Returns whether or not a sequence has been placed into the iterator (_seq is not None).

set_sequence( seq)
Sets the _seq to seq.

reset_index( )
If the <al-for> tag does not contain a continue attribute then this is called just before executing the tag content for the first element in the sequence. It sets the _index member to _start.

reset_count( )
This is called just before executing the tag content for the first element in the sequence. It sets the _count member to zero.

clear_value( )
Sets the _have_value member to None which causes the next call of has_value() to retrieve the sequence element indexed by _index.

has_value( )
When the _have_value member is None this method tries to retrieve the sequence element indexed by _index. If an element is returned by the sequence it is saved in the _value member and _have_value is set to one. If an IndexError exception is raised by the sequence then _have_value is set to zero.

The method returns TRUE if a sequence member is contained in _value.

By this mechanism the iterator retrieves each value from the sequence exactly once.

next( )
Retrieves the next value (if available) from the sequence into the _value member.

set_value( value)
A back door hack for multi-column output that sets respective values of the iterator to sequences created by slicing the sequence in the expr attribute of the <al-for> tag.