diff --git a/src/caosdb/common/models.py b/src/caosdb/common/models.py
index 3b225b337b987afef38192d8d33b2d5d88e57769..6ec49df2722170805fb6230753f36503870a8821 100644
--- a/src/caosdb/common/models.py
+++ b/src/caosdb/common/models.py
@@ -429,7 +429,7 @@ class Entity(object):
return self
def add_parent(self, parent=None, **kwargs): # @ReservedAssignment
- """Add a parent to this entity
+ """Add a parent to this entity.
Parameters
----------
@@ -447,19 +447,23 @@ class Entity(object):
Name of the parent entity. Ignored if `parent is not
none`.
inheritance : str
- One of `"obligatory"`, `"recommended"`, `"suggested"`,
- or `"fix"`. Specifies the importance of the properties
- of the parent that will be inherited by this
- entity. If no `inheritance` is given, no properties
- will be inherited by the child.
+ One of ``obligatory``, ``recommended``, ``suggested``, or ``fix``. Specifies the
+ minimum importance which parent properties need to have to be inherited by this
+ entity. If no `inheritance` is given, no properties will be inherited by the child.
+ This parameter is case-insensitive.
+
+ Note that the behaviour is currently not yet specified when assigning parents to
+ Records, it only works for inheritance of RecordTypes (and Properties).
+
+ For more information, it is recommended to look into the
+ :ref:`data insertion tutorial<tutorial-inheritance-properties>`.
Raises
------
UserWarning
- If neither a 'parent' parameter, nor the 'id', nor 'name'
+ If neither a `parent` parameter, nor the `id`, nor `name`
parameter is passed to this method.
-
"""
name = (kwargs['name'] if 'name' in kwargs else None)
pid = (kwargs['id'] if 'id' in kwargs else None)
@@ -1466,7 +1470,7 @@ class Property(Entity):
Additional keyword arguments specifying the parent Entity
by id or name, and specifying the inheritance level. See
:py:meth:`Entity.add_parent` for more information. Note
- that by default, `inheritance` is set to `FIX`.
+ that by default, `inheritance` is set to ``fix``.
See Also
--------
@@ -1562,7 +1566,7 @@ class RecordType(Entity):
Additional keyword arguments specifying the parent Entity by id or
name, and specifying the inheritance level. See
:py:meth:`Entity.add_parent` for more information. Note
- that by default, `inheritance` is set to `OBLIGATORY`.
+ that by default, `inheritance` is set to ``obligatory``.
See Also
--------
diff --git a/src/doc/tutorials/Data-Insertion.rst b/src/doc/tutorials/Data-Insertion.rst
index 51678e868c2f1854b87001b1fcae883fac656d39..22fb9461d6916003b2dad496ff3487df335c8dcc 100644
--- a/src/doc/tutorials/Data-Insertion.rst
+++ b/src/doc/tutorials/Data-Insertion.rst
@@ -4,11 +4,9 @@ Data Insertion
Data Models
~~~~~~~~~~~
-Data is stored and structured in CaosDB using a concept of
-RecordTypes, Properties, Records etc. If you do not know what these
-are, please look at the chapter `Data Model
-<https://docs.indiscale.com/caosdb-server/specification/Datatype.html>`_
-in the CaosDB server documentation.
+Data is stored and structured in CaosDB using a concept of RecordTypes, Properties, Records etc. If
+you do not know what these are, please look at the chapter :doc:`Data
+Model<caosdb-server:Data-Model>` in the CaosDB server documentation.
In order to insert some actual data, we need to create a data model
using RecordTypes and Properties (You may skip this if you use a CaosDB
@@ -37,11 +35,12 @@ two more Properties and a RecordType:
container.extend([a, b, epsilon, recordtype])
container.insert()
+.. _tutorial-inheritance-properties:
Inheritance of Properties
-------------------------
-Suppose you want to insert a new RecordType “2D_BarkleySimulation”
+Suppose you want to create a new RecordType “2D_BarkleySimulation”
that denotes spatially extended Barkley simulations. This is a subtype
of the “BarkleySimulation” RecordType above and should have all its
parameters, i.e., properties. It may be assigned more, e.g., spatial
@@ -49,7 +48,7 @@ resolution, but we'll omit this for the sake of brevity for now.
.. code:: python
- rt = db.RecordType(name="2D_BarkleySimulation",
+ rt = db.RecordType(name="2D_BarkleySimulation",
description="Spatially extended Barkley simulation")
# inherit all properties from the BarkleySimulation RecordType
rt.add_parent(name="BarkleySimulation", inheritance="all")
@@ -58,20 +57,20 @@ resolution, but we'll omit this for the sake of brevity for now.
print(rt.get_property(name="epsilon").importance) ### rt has a "epsilon" property with the same importance as "BarkleySimulation"
The parameter ``inheritance=(obligatory|recommended|fix|all|none)`` of
-``add_parent`` tells the server to assign all properties of the parent
-RecordType with the chosen importance to the child RecordType
+:py:meth:`Entity.add_parent()<caosdb.common.models.Entity.add_parent>` tells the server to assign
+all properties of the parent RecordType with the chosen importance (and properties with a higher
+importance) to the child RecordType
automatically upon insertion. See the chapter on `importance
-<https://docs.indiscale.com/caosdb-server/specification/RecordType.html#importance>`_
-in the documentation of the CaosDB server for more information on the
-importance and inheritance of properties.
+<https://docs.indiscale.com/caosdb-server/specification/RecordType.html#importance>`_ in the
+documentation of the CaosDB server for more information on the importance and inheritance of
+properties.
.. note::
- The inherited properties will only be present after the insertion
- since they have to be set by the CaosDB server, not by the Python
- Client.
+ The inherited properties will only be visible after the insertion since they are set by the
+ CaosDB server, not by the Python client.
+
-
Insert Actual Data
~~~~~~~~~~~~~~~~~~