5.3.7.1 ListIterator Objects
The iterator named in the iter 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.5.
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.