File: al_tree.rst

package info (click to toggle)
python-django-treebeard 4.7.1-1
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 988 kB
  • sloc: python: 5,317; javascript: 258; makefile: 180; sh: 6
file content (106 lines) | stat: -rw-r--r-- 3,485 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
Adjacency List trees
====================

.. module:: treebeard.al_tree

This is a simple implementation of the traditional Adjacency List Model for
storing trees in relational databases.

In the adjacency list model, every node will have a
":attr:`~AL_Node.parent`" key, that will be NULL for root nodes.

Since ``django-treebeard`` must return trees ordered in a predictable way,
the ordering for models without the :attr:`~AL_Node.node_order_by`
attribute will have an extra attribute that will store the relative
position of a node between it's siblings: :attr:`~AL_Node.sib_order`.

The adjacency list model has the advantage of fast writes at the cost of
slow reads. If you read more than you write, use
:class:`~treebeard.mp_tree.MP_Node` instead.

.. warning::

   As with all tree implementations, please be aware of the
   :doc:`caveats`.


.. inheritance-diagram:: AL_Node
.. autoclass:: AL_Node
   :show-inheritance:

   .. warning::

     If you need to define your own
     :py:class:`~django.db.models.Manager` class,
     you'll need to subclass
     :py:class:`~AL_NodeManager`.


   .. attribute:: node_order_by

      Attribute: a list of model fields that will be used for node
      ordering. When enabled, all tree operations will assume this ordering.

      Example:

      .. code-block:: python

         node_order_by = ['field1', 'field2', 'field3']

   .. attribute:: parent

      ``ForeignKey`` to itself. This attribute **MUST** be defined in the
      subclass (sadly, this isn't inherited correctly from the ABC in
      `Django 1.0`). Just copy&paste these lines to your model:

      .. code-block:: python

               parent = models.ForeignKey('self',
                                          related_name='children_set',
                                          null=True,
                                          db_index=True)

   .. attribute:: sib_order

      ``PositiveIntegerField`` used to store the relative position of a node
      between it's siblings. This attribute is mandatory *ONLY* if you don't
      set a :attr:`node_order_by` field. You can define it copy&pasting this
      line in your model:

      .. code-block:: python

              sib_order = models.PositiveIntegerField()

   Examples:

   .. code-block:: python

           class AL_TestNode(AL_Node):
               parent = models.ForeignKey('self',
                                          related_name='children_set',
                                          null=True,
                                          db_index=True)
               sib_order = models.PositiveIntegerField()
               desc = models.CharField(max_length=255)

           class AL_TestNodeSorted(AL_Node):
               parent = models.ForeignKey('self',
                                          related_name='children_set',
                                          null=True,
                                          db_index=True)
               node_order_by = ['val1', 'val2', 'desc']
               val1 = models.IntegerField()
               val2 = models.IntegerField()
               desc = models.CharField(max_length=255)


   Read the API reference of :class:`treebeard.models.Node` for info on
   methods available in this class, or read the following section for methods
   with particular arguments or exceptions.
   
   .. automethod:: get_depth

        See: :meth:`treebeard.models.Node.get_depth`

.. autoclass:: AL_NodeManager
  :show-inheritance: