easytree.list#

class easytree.list(args=None, *, sealed=False, frozen=False)#

Parameters:

args (iterable, None) – an iterable values
sealed (bool) – True if list is sealed, False otherwise
frozen (bool) – True if list is frozen, False otherwise

Note

Lists and dicts included or appended in the list are recursively sealed and frozen as per its containing parent.

append(*args, **kwargs)#

Append a value to the list

Note

The append method can take either one positional argument or one-to-many named (keyword) arguments. If passed keyword arguments, the kwargs dictionary is added to the list as an easytree.dict.

Returns:

item – the last added item

Return type:

any

Raises:

TypeError – if the list is sealed or frozen
ValueError – if neither a value nor a set of kwargs is given

Example

>>> tree = easytree.list()                                # list node
>>> tree.append("hello world")                            # simple append
>>> tree.append(name="David", age=29)                     # call with kwargs
>>> tree.append({"animal":"elephant", "country":"India"}) # call with dict
>>> tree
[
    "Hello world",
    {
        "name": "David",
        "age": 29
    },
    {
        "animal": "elephant",
        "country": "India"
    }
]

Note

The append method intentionally returns a reference to the last-added item. This allows for fluent code using the context manager.

Example

>>> chart = easytree.dict()
>>> with chart.axes.append({}) as axis:
...     axis.title.text = "primary axis"
>>> with chart.axes.append({}) as axis:
...     axis.title.text = "secondary axis"
>>> chart
{
    "axes": [
        {
            "title": {
                "text": "primary axis"
            }
        },
        {
            "title": {
                "text": "secondary axis"
            }
        }
    ]
}

clear()#

Remove all items from the list.

Return type:: None
Raises:: TypeError – if the list is sealed or frozen

copy()#

Return a shallow copy of the list

Returns:: copy – the new list
Return type:: list

extend(other)#

Extend the list by appending all the items from another iterable.

list or dict items from other are cast to easytree.list or easytree.dict values respectively.

Parameters:: other (iterable) – the other iterable
Return type:: None
Raises:: TypeError – if the list is sealed or frozen

insert(index, value)#

Insert an item into the list at a given position.

If the value is a list or a dict, the value is cast to an easytree.list or easytree.dict

Parameters:

index (int) – the index at which to insert the value
value (any) – the inserted value

Return type:

None

Raises:

TypeError – if the list is sealed or frozen

pop(*args)#

Remove the item at the given position in the list, and return it.

Returns:: item – the popped item
Return type:: any
Raises:: TypeError – if the list is sealed or frozen

remove(x)#

Remove the first item from the list whose value is equal to x.

Parameters:

x (any) – the value to remove

Return type:

None

Raises:

TypeError – if the list is sealed or frozen
ValueError – if there is no such item

reverse()#

Reverse the elements of the list in place.

Return type:: None
Raises:: TypeError – if the list is sealed or frozen

sort(*, key=None, reverse=False)#

Sort the items of the list in place

Return type:: None
Raises:: TypeError – if the list is frozen