Metadata-Version: 2.1
Name: propertree
Version: 1.1.0.post5
Summary: Library to help create meaningful structures from yaml or json.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: importlib-metadata; python_version >= "3.8"

# Propertree

Map Python data structures to classes and create tree of resolvable objects.

## Overview

This library provides a set of classes that can be used to take Python data
structures and map them to a set of properties organised in a tree-like
structure. The basic idea is that a Python object with one or more attributes
can be represented by a unique key in a dictionary whereby the the value of
that key represents the internal makeup of the object i.e. attributes etc.

The basic design is as follows:

A ```PTreeSection``` object takes Python data structures dict/list/literal
after having been converted from YAML or JSON. This input is treated like a
tree of properties whereby each level of a structure equates to a branch
containing a set of "property overrides" which are identified by a unique
root key that maps to an implementation of ```PTreeOverrideBase```. Descendant
lists, dictionaries or unknown literals are treated new branches.

Once the whole tree has been mapped, objects can be retreived by either
iterating over the root object or accessing them directly as attributes.

For example lets say we have the following YAML:

```
config:
  fire:
    danger:
      level: high
  banana:
    danger:
      level: low
```

And the following accompanying Python code:

```
from propertree.propertree2 import PTreeOverrideBase, PTreeSection

class Config(PTreeOverrideBase):
  _override_keys = ['config']


root = PTreeSection(MYYAML)
```

We can then access the config as follows:

```
print(root.config.fire.danger.level)
print(root.config.banana.danger.level)
```

## Property Inheritance

Property inheritance is supported by passing down all properties identified at
a branch level to all descendent branches. This allows property objects to
access any property within it's call chain although it would be the most
recently overriden version if one exists. For example:

```
input: /etc/foo
checks:
  chk1:
    input: /etc/bar
    condition: C1
  chk2:
    condition: C2
```

In the above, ```checks.chk1.input``` would be "/etc/bar" whereas ```checks.chk2.input``` would be "/etc/foo".


## Mapped Properties

It is possible to compose complex properties made up of one or more "member"
properties. These are called *mapped* properties and are provided by the
```PTreeMappedOverrideBase``` class. A mapped property has two parts; a *primary*
and its *members*. A property can only be a member of one mapped property (i.e.
be associated with a single primary). These properties also have the special
feature that allow them to be defined either *explicitly* using their
full construct i.e. primary and members or *implicitly* using just their
members. If the latter form is used, the primary is implicitly created such
that when the members are accessed it is always done through the primary.

For example, here is some code to define a mapped property:

```
from propertree.propertree2 import PTreeOverrideBase, PTreeMappedOverrideBase, PTreeSection

class MapPrimary(PTreeMappedOverrideBase):
  _override_keys = ['mapprimary']
  _override_members = ['member1']


class Member1(PTreeOverrideBase):
  _override_keys = ['member1']

...
```

the following will both behave the same when accessed:

The explicit declaration:

```
mapprimary:
  member1:
    attr1:
```

And the counterpart implicit declaration:

```
member1:
  attr1:
```

Are both accessed as follows:

```
mapprimary.member1.attr1
```

## Logical Groupings

Sometimes it might be useful to represent properties or content within a
property as a logical function. To achieve this, propertree has builtin
logical operator properties which map to the ```PTreeLogicalGrouping``` class.
This class provides a default implementation of logical operations that can be
used by any property. Grouped items are expected to have a ```result```
attribute that returns a boolean result such that the respective logical
operator of that grouping is then applied to the set of all results.

In the following example we have a top-level operator with two items, each of
which is itself an operator, the first having two property items and second
having one. This equates to AND(OR(P1, P2), NOT(P3)).

```
and:
  or: [P1, P2]
  not: P3
```

Example code for this would look like:

```
from propertree.propertree2 import PTreeSection

root = PTreeSection(MYYAML)
result = root.and.result
```

