deprecated

easytree.Tree

alias of Node

class easytree.Node(value=None, *args, **kwargs)

Attention

This class is deprecated since 0.2.0 and may be removed in future versions. Use easytree.dict or easytree.list instead.

A recursive tree structure, supporting both dict and list nodes. New children nodes can be read and written as attributes, and dynamically become nodes themselves.

Example

>>> root = easytree.Tree()
>>> root.user.firstname = "foo"
>>> root.user.firstname == root["user"]["firstname"] == "foo"
True
>>> root.user.friends.append(username="@jack")
>>> root
{
    "user":{
        "firstname":"foo"
    },
    "friends":[
        {
            "username":"@jack"
        }
    ]
}

The type of a newly-accessed node is initially undefined, but is cast as a dict or a list depending on subsequent interactions.

Example

>>> root = easytree.Tree()
>>> root.abc                              #abc is an undefined node
>>> root.abc.xyz                          #abc is cast to a dict node; xyz is undefined
>>> root.abc.xyz.append(firstname="Bob")  #xyz is cast to a list node with one dict node

A tree can be serialized back to native python objects using the serialize method

Example

>>> tree = easytree.Tree()
>>> tree.abc.xyz.append(44)
>>> tree.serialize()
{
    "abc":{
        "xyz:[
            44
        ]
    }
}

A tree can be sealed or frozen to prevent further changes

Example

>>> tree = easytree.Tree({"abc":{"xyz":True}}, sealed=True)
>>> tree.abc.xyz = False
>>> tree.foo = "bar"
AttributeError: cannot set new attribute 'foo' on sealed node

append(*args, **kwargs)

Appends a value to a list node. If the node type was previously undefined, the node becomes a list.

Note

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

Examples

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

Note

The append method intentionally returns a reference to the last-added item, if that item is a new node. This allows for fluent code using the context manager.

Example

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

deepget(keys, default=None)

Returns the value at the end of the keys’ path, or default if such path raises an KeyError or IndexError

Parameters:

• keys (iterable) – list of keys

• default – default value if keys’ path does not exists

Example

>>> tree = easytree.Tree({"address":{"city":"New York"}})
>>> tree.deepget(("address","city"))
"New York"
>>> tree.deepget(("address","country"), "US")
"US"

get(key, default=None)

Returns the value at a given key, or default if the key does not exists.

Example

>>> config = easytree.Tree({"context":{"starting":"2016-03-31"}})
>>> config.context.get("starting", "2014-01-01")
2016-03-31
>>> config.context.get("ending", "2021-12-31")
2021-12-31
>>> config.context.get("calendar")
None

items()

Returns the items at the dict node

Return type:

dict_items

Raises:

AttributeError – if node is a list node

keys()

Returns the keys at the dict node

Return type:

dict_keys

Raises:

AttributeError – if node is a list node

pop(*args, **kwargs)

Removes (in-place) the item at given key/index and returns the corresponding value.

Note

Calling pop on an undefined node

Example

>>> tree = easytree.Tree({"name":"Bob","numbers":[1,3,5], "address":{"country":"US"}})
>>> tree.pop("name")
"Bob"
>>> tree
easytree.Tree({"numbers":[1,3,5], "address":{"country":"US"}})
>>> tree.numbers.pop()
5
>>> tree
easytree.Tree({"numbers":[1,3], "address":{"country":"US"}})

serialize()

Attention

Deprecated since 0.2.0

Recursively converts itself to a native python type (dict, list or None).

Example

>>> chart = easytree.Tree()
>>> chart.chart.type = "bar"
>>> chart.title.text = "France Olympic Medals"
>>> chart.xAxis.categories = ["Gold", "Silver", "Bronze"]
>>> chart.yAxis.title.text = "Count"
>>> chart.series.append(name="2016", data=[10, 18, 14])
>>> chart.series.append({"name":"2012", "data":[11,11,13]})
>>> chart.serialize()
{
    "chart": {
        "type": "bar"
    },
    "title": {
        "text": "France Olympic Medals"
    },
    "xAxis": {
        "categories": [
            "Gold",
            "Silver",
            "Bronze"
        ]
    },
    "yAxis": {
        "title": {
            "text": "Count"
        }
    },
    "series": [
        {
            "name": "2016",
            "data": [
                10,
                18,
                14
            ]
        },
        {
            "name": "2012",
            "data": [
                11,
                11,
                13
            ]
        }
    ]
}

update(other)

Updates (in place) the dict node with other mapping

Note

An undefined node will be cast as a dict node

Return type:

None

Raises:

AttributeError – if node is a list node

values()

Returns the values at the dict node

Return type:

dict_values

Raises:

AttributeError – if node is a list node

easytree.dump(obj, stream, *args, **kwargs)

Attention

Deprecated since 0.2.0

Serialize Tree object as a JSON formatted string to stream (a .write()-supporting file-like object).

*args and **kwargs are passed to the json.dump function

Example

>>> tree = easytree.Tree({"foo": "bar"})
>>> with open("data.json", "w") as file:
...     easytree.dump(tree, file, indent=4)

easytree.dumps(obj, *args, **kwargs)

Attention

Deprecated since 0.2.0

Serialize Tree to a JSON formatted string.

*args and **kwargs are passed to the json.dumps function

easytree.load(stream, *args, frozen=False, sealed=False, **kwargs)

Attention

Deprecated since 0.2.0

Deserialize a text file or binary file containing a JSON document to an Tree object

*args and **kwargs are passed to the json.load function

Example

>>> with open("data.json", "r") as file:
...     tree = easytree.load(file)

easytree.loads(s, *args, frozen=False, sealed=False, **kwargs)

Attention

Deprecated since 0.2.0

Deserialize s (a str, bytes or bytearray instance containing a JSON document) to an Tree object

*args and **kwargs are passed to the json.loads function

easytree.new(root=None, *, sealed: bool = False, frozen: bool = False)

Attention

Deprecated since 0.2.0

Creates a new easytree.Tree

Return type:

easytree.Tree

easytree.serialize(tree: Node)

Attention

Deprecated since 0.2.0

Recursively converts an easytree.Tree back to a native python type.

Example

>>> chart = easytree.Tree()
>>> chart.chart.type = "bar"
>>> chart.title.text = "France Olympic Medals"
>>> chart.xAxis.categories = ["Gold", "Silver", "Bronze"]
>>> chart.yAxis.title.text = "Count"
>>> chart.series.append(name="2016", data=[10, 18, 14])
>>> chart.series.append({"name":"2012", "data":[11,11,13]})
>>> easytree.serialize(chart)
{
    "chart": {
        "type": "bar"
    },
    "title": {
        "text": "France Olympic Medals"
    },
    "xAxis": {
        "categories": [
            "Gold",
            "Silver",
            "Bronze"
        ]
    },
    "yAxis": {
        "title": {
            "text": "Count"
        }
    },
    "series": [
        {
            "name": "2016",
            "data": [
                10,
                18,
                14
            ]
        },
        {
            "name": "2012",
            "data": [
                11,
                11,
                13
            ]
        }
    ]
}