fix issue 151 - cascades to part tables should be from parent tables only.

Author: dimitri-yatsenko

datajoint/table.py

@@ -46,16 +46,17 @@ class _RenameMap(tuple):
 
 class Table(QueryExpression):
     """
-    Table is an abstract class that represents a base relation, i.e. a table in the schema.
+    Table is an abstract class that represents a table in the schema.
+    It implements insert and delete methods and inherits query functionality.
     To make it a concrete class, override the abstract properties specifying the connection,
     table name, database, and definition.
-    A Relation implements insert and delete methods in addition to inherited relational operators.
     """
 
     _table_name = None  # must be defined in subclass
     _log_ = None  # placeholder for the Log table object
 
-    # These properties must be set by the schema decorator (schemas.py) at class level or by FreeTable at instance level
+    # These properties must be set by the schema decorator (schemas.py) at class level
+    # or by FreeTable at instance level
     database = None
     declaration_context = None
 
@@ -65,7 +66,8 @@ def table_name(self):
 
     @property
     def definition(self):
-        raise NotImplementedError('Subclasses of Table must implement the `definition` property')
+        raise NotImplementedError(
+            'Subclasses of Table must implement the `definition` property')
 
     def declare(self, context=None):
         """
@@ -95,7 +97,8 @@ def alter(self, prompt=True, context=None):
         """
         if self.connection.in_transaction:
             raise DataJointError(
-                'Cannot update table declaration inside a transaction, e.g. from inside a populate/make call')
+                'Cannot update table declaration inside a transaction, '
+                'e.g. from inside a populate/make call')
         if context is None:
             frame = inspect.currentframe().f_back
             context = dict(frame.f_globals, **frame.f_locals)
@@ -117,7 +120,8 @@ def alter(self, prompt=True, context=None):
                     # skip if no create privilege
                     pass
                 else:
-                    self.__class__._heading = Heading(table_info=self.heading.table_info)  # reset heading
+                    # reset heading
+                    self.__class__._heading = Heading(table_info=self.heading.table_info)
                     if prompt:
                         print('Table altered')
                     self._log('Altered ' + self.full_table_name)
@@ -226,9 +230,11 @@ def external(self):
     def update1(self, row):
         """
         update1 updates one existing entry in the table.
-        Caution: Updates are not part of the DataJoint data manipulation model. For strict data integrity,
-        use delete and insert.
-        :param row: a dict containing the primary key and the attributes to update.
+        Caution: In DataJoint the primary modes for data manipulation is to insert and delete
+        entire records since referential integrity works on the level of records, not fields.
+        Therefore, updates are reserved for corrective operations outside of main workflow.
+        Use UPDATE methods sparingly with full awareness of potential violations of assumptions.
+        :param row: a dict containing the primary key values and the attributes to update.
         Setting an attribute value to None will reset it to the default value (if any)
         The primary key attributes must always be provided.
         Examples:
@@ -241,7 +247,8 @@ def update1(self, row):
         if not set(row).issuperset(self.primary_key):
             raise DataJointError('The argument of update1 must supply all primary key values.')
         try:
-            raise DataJointError('Attribute `%s` not found.' % next(k for k in row if k not in self.heading.names))
+            raise DataJointError('Attribute `%s` not found.' %
+                                 next(k for k in row if k not in self.heading.names))
         except StopIteration:
             pass  # ok
         if len(self.restriction):
@@ -250,7 +257,8 @@ def update1(self, row):
         if len(self & key) != 1:
             raise DataJointError('Update entry must exist.')
         # UPDATE query
-        row = [self.__make_placeholder(k, v) for k, v in row.items() if k not in self.primary_key]
+        row = [self.__make_placeholder(k, v) for k, v in row.items()
+               if k not in self.primary_key]
         query = "UPDATE {table} SET {assignments} WHERE {where}".format(
             table=self.full_table_name,
             assignments=",".join('`%s`=%s' % r[:2] for r in row),
@@ -259,22 +267,25 @@ def update1(self, row):
 
     def insert1(self, row, **kwargs):
         """
-        Insert one data record or one Mapping (like a dict).
-        :param row: a numpy record, a dict-like object, or an ordered sequence to be inserted as one row.
+        Insert one data record into the table..
+        :param row: a numpy record, a dict-like object, or an ordered sequence to be inserted
+        as one row.
         For kwargs, see insert()
         """
         self.insert((row,), **kwargs)
 
-    def insert(self, rows, replace=False, skip_duplicates=False, ignore_extra_fields=False, allow_direct_insert=None):
+    def insert(self, rows, replace=False, skip_duplicates=False, ignore_extra_fields=False,
+               allow_direct_insert=None):
         """
         Insert a collection of rows.
-        :param rows: An iterable where an element is a numpy record, a dict-like object, a pandas.DataFrame, a sequence,
-            or a query expression with the same heading as table self.
+        :param rows: An iterable where an element is a numpy record, a dict-like object, a
+            pandas.DataFrame, a sequence, or a query expression with the same heading as self.
         :param replace: If True, replaces the existing tuple.
         :param skip_duplicates: If True, silently skip duplicate inserts.
         :param ignore_extra_fields: If False, fields that are not in the heading raise error.
         :param allow_direct_insert: applies only in auto-populated tables.
-                                    If False (default), insert are allowed only from inside the make callback.
+                                    If False (default), insert are allowed only from inside
+                                    the make callback.
         Example::
         >>> relation.insert([
         >>>     dict(subject_id=7, species="mouse", date_of_birth="2014-09-01"),
@@ -288,20 +299,22 @@ def insert(self, rows, replace=False, skip_duplicates=False, ignore_extra_fields
             ).to_records(index=False)
 
         # prohibit direct inserts into auto-populated tables
-        if not allow_direct_insert and not getattr(self, '_allow_insert', True):  # allow_insert is only used in AutoPopulate
+        if not allow_direct_insert and not getattr(self, '_allow_insert', True):
             raise DataJointError(
-                'Inserts into an auto-populated table can only done inside its make method during a populate call.'
+                'Inserts into an auto-populated table can only done inside '
+                'its make method during a populate call.'
                 ' To override, set keyword argument allow_direct_insert=True.')
 
-        if inspect.isclass(rows) and issubclass(rows, QueryExpression):   # instantiate if a class
-            rows = rows()
+        if inspect.isclass(rows) and issubclass(rows, QueryExpression):
+            rows = rows()  # instantiate if a class
         if isinstance(rows, QueryExpression):
             # insert from select
             if not ignore_extra_fields:
                 try:
                     raise DataJointError(
-                        "Attribute %s not found. To ignore extra attributes in insert, set ignore_extra_fields=True." %
-                        next(name for name in rows.heading if name not in self.heading))
+                        "Attribute %s not found. To ignore extra attributes in insert, "
+                        "set ignore_extra_fields=True." % next(
+                            name for name in rows.heading if name not in self.heading))
                 except StopIteration:
                     pass
             fields = list(name for name in rows.heading if name in self.heading)
@@ -369,10 +382,21 @@ def _delete_cascade(self):
                             *[_.strip('`') for _ in match['child'].split('`.`')]
                             )).fetchall())))
                     match['parent'] = match['parent'][0]
-                # restrict child by self if
-                # 1. if self's restriction attributes are not in child's primary key
-                # 2. if child renames any attributes
-                # otherwise restrict child by self's restriction.
+
+                # If child is a part table of another table, do not recurse (See issue #151)
+                if '__' in match['child'] and (not match['child'].strip('`').startswith(
+                        self.full_table_name).strip('`') + '__'):
+                    raise DataJointError(
+                        'Attempt to delete from part table {part} before deleting from '
+                        'its master. Delete from {master} first.'.format(
+                            part=match['child'],
+                            master=match['child'].split('__')[0] + '`'
+                        ))
+
+                # Restrict child by self if
+                #   1. if self's restriction attributes are not in child's primary key
+                #   2. if child renames any attributes
+                # Otherwise restrict child by self's restriction.
                 child = FreeTable(self.connection, match['child'])
                 if set(self.restriction_attributes) <= set(child.primary_key) and \
                         match['fk_attrs'] == match['pk_attrs']:
@@ -396,6 +420,8 @@ def delete(self, transaction=True, safemode=None):
         Deletes the contents of the table and its dependent tables, recursively.
 
         :param transaction: if True, use the entire delete becomes an atomic transaction.
+            This is the default and recommended behavior. Set to False if this delete is nested
+            within another transaction.
         :param safemode: If True, prohibit nested transactions and prompt to confirm. Default
             is dj.config['safemode'].
         :return: number of deleted rows (excluding those from dependent tables)
@@ -460,7 +486,7 @@ def drop(self):
         User is prompted for confirmation if config['safemode'] is set to True.
         """
         if self.restriction:
-            raise DataJointError('A relation with an applied restriction condition cannot be dropped.'
+            raise DataJointError('A table with an applied restriction cannot be dropped.'
                                  ' Call drop() on the unrestricted Table.')
         self.connection.dependencies.load()
         do_drop = True
@@ -555,12 +581,14 @@ def describe(self, context=None, printout=True):
 
     def _update(self, attrname, value=None):
         """
-            This is a deprecated function to be removed in datajoint 0.14. Use .update1 instead.
+            This is a deprecated function to be removed in datajoint 0.14.
+            Use .update1 instead.
 
-            Updates a field in an existing tuple. This is not a datajoyous operation and should not be used
-            routinely. Relational database maintain referential integrity on the level of a tuple. Therefore,
-            the UPDATE operator can violate referential integrity. The datajoyous way to update information is
-            to delete the entire tuple and insert the entire update tuple.
+            Updates a field in one existing tuple. self must be restricted to exactly one entry.
+            In DataJoint the principal way of updating data is to delete and re-insert the
+            entire record and updates are reserved for corrective actions.
+            This is because referential integrity is observed on the level of entire
+            records rather than individual attributes.
 
             Safety constraints:
                1. self must be restricted to exactly one tuple