index.rst 3 KB
Newer Older
1 2 3
augmentedtree
=============

4 5 6 7 8
.. augmentedtree documentation master file, created by
   sphinx-quickstart on Thu Jan 17 21:49:20 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

9 10 11 12 13 14 15 16 17 18 19
.. image:: resources/augmentedtree-icon.png
   :height: 192px
   :width: 192px
   :alt: Circle, square, triangle and lines.
   :align: center


`augmentedtree` enhances mappings and sequences (targeted for python
dictionaries and lists) preserving their native behavior and access.
The enhancement comes with getting values by single keys, human readable
viewing, selecting and setting multiple values/items within the nested
20 21 22 23
data at once, *or*-conditional selection of values/items. Also this package
intends to prepare the nested data for pyQt. The augmentation provides
methods and properties to be used for a `QAbstractItemModel` showing
the nested data within a `QTreeView`.
24

25 26 27 28 29 30 31
Installation
------------

Installing the latest release using pip is recommended.

::

David Scheliga's avatar
David Scheliga committed
32
   $ pip install augmentedtree
33 34 35 36 37

The latest development state can be obtained from gitlab using pip.

::

David Scheliga's avatar
David Scheliga committed
38
   $ pip install git+https://gitlab.com/david.scheliga/[email protected]
39 40


41 42
Purpose of *augmentedtree*
--------------------------
43 44 45 46 47 48 49 50 51 52 53 54 55

The main purpose of this package is enhance nested data structure (mostly nested
dictionaries) by keeping its functionality for methods working with these data types.

The targeted usage is to be able to write the following kind of code

.. code-block:: python

   # code where the nested data comes from
   ...

   # gathering parameters
   with AugmentedTree(nested_data) as tree:
56 57 58 59 60 61 62 63
      # simple selection
      first_value = tree.select("something", "here")[0]
      last_value = tree.select("something", "there")[-1]
      a_slice_of_values = tree.select("a", "l?t", "of")[3:6]

      # selection with refinement
      selection_of_values = tree.select("also/a", "lot", "of")
      narrowed_down = selection_of_values.where("this", "or", "that")[ALL_ITEMS]
64 65 66 67 68 69 70 71 72
       ...

   if not tree.all_selections_succeeded:
       # break, exit or reacting to some value are not there
       ...

   # code which is working with requested parameters
   ...

73 74 75
Limitations
-----------

76 77 78 79 80 81 82 83 84
The augmented tree items are directly forwarding the nested data. Practically objects
implementing collections.abc.Sequence and collection.abc.Mapping should work with this
package. Nevertheless:

- This package was developed with using `list` and `dict`. Other classes weren't tested
  yet.
- Keep in mind that inserting new items directly into the nested data will mess up
  the augmentation. If `AnAugmentedTreeItem` should keep track of new items usage of
  this layer is mandatory.
85

86 87 88
The **development status** is **alpha**.

- Changes will come.
89 90
- Definition of types for fields in MappingTreeItem will be implemented.
- **Selection** items will be reworked. (SPARQL support is a desirable option.)
91 92


93
.. toctree::
David Scheliga's avatar
David Scheliga committed
94
   :maxdepth: 3
95 96 97 98
   :caption: Contents:

   basic_usage
   detailed_examples
99
   an_augmented_tree_item
David Scheliga's avatar
David Scheliga committed
100
   package/package