Lists

This section describes the following classes:

• dragonfly.grammar.list.ListBase – the base list class

• dragonfly.grammar.list.List – sub-class of Python’s built-in list type. It can be updated and modified without reloading a grammar.

• dragonfly.grammar.list.DictList – sub-class of Python’s built-in dict type. It can be updated and modified without reloading a grammar.

The List Updates section discusses possible performance issues with modifying Dragonfly lists and ways to avoid these issues altogether.

List classes

class ListBase(name)

Base class for dragonfly list objects.

property valid_types

The types of object at a Dragonfly list can contain.

property name

Read-only access to a list’s name.

property grammar

Set-once access to a list’s grammar object.

class List(name, *args, **kwargs)

Wrapper for Python’s built-in list that supports automatic engine notification of changes.

Use ListRef elements in a grammar rule to allow matching speech to list items.

set(other)

Set the contents of this list to the contents of another.

append(*args, **kwargs)

Append object to the end of the list.

extend(*args, **kwargs)

Extend list by appending elements from the iterable.

insert(*args, **kwargs)

Insert object before index.

pop(*args, **kwargs)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(*args, **kwargs)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(*args, **kwargs)

Reverse IN PLACE.

sort(*args, **kwargs)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

property grammar

Set-once access to a list’s grammar object.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

property name

Read-only access to a list’s name.

property valid_types

The types of object at a Dragonfly list can contain.

class DictList(name, *args, **kwargs)

Wrapper for Python’s built-in dict that supports automatic engine notification of changes. The object’s keys are used as the elements of the engine list, while use of the associated values is left to the user.

Use DictListRef elements in a grammar rule to allow matching speech to dictionary keys.

set(other)

Set the contents of this dict to the contents of another.

clear() → None.  Remove all items from D.

fromkeys(*args, **kwargs)

Create a new dictionary with keys from iterable and values set to value.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, default is returned if given, otherwise KeyError is raised

popitem(*args, **kwargs)

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(*args, **kwargs)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

copy() → a shallow copy of D

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

property grammar

Set-once access to a list’s grammar object.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

property name

Read-only access to a list’s name.

property valid_types

The types of object at a Dragonfly list can contain.

values() → an object providing a view on D's values

List Updates

Lists are updated after each modifying operation, e.g. list.append(), list.remove(), dict[key] = value, dict.pop(), etc. This is fine for a few list modifications here and there, but is inefficient for adding / removing many items at once.

The simplest solution is to use the ListBase context manager:

# Do list modification inside a 'with' block to only do one list update
# at the end.
my_list = List("my_list")
with my_list:
    for x in range(50):
        my_list.append(str(x))

Some methods like list.extend() or dict.update() will also only update the list once afterwards:

# Add multiple list items using extend().
my_list = List("my_list")
my_list.extend([str(x) for x in range(50)])

# Add multiple dictionary keys using update().
dictionary = DictList("dictionary")
dictionary.update({str(x):x for x in range(50)})