tweaked docs and added notes for later

draftsman/classes/blueprint.py

@@ -447,8 +447,12 @@ class named :py:class:`.EntityList`, which has all the normal properties
         of a regular list, as well as some extra features. For more information
         on ``EntityList``, check out this writeup
         :ref:`here <handbook.blueprints.blueprint_differences>`.
-        Note - assigning to this triggers a deep copy, so use .append()
-        or .extend() if you're building incrementally.
+
+        .. NOTE ::
+            
+            Currently, assigning to this always triggers a deep copy. To avoid
+            this, use :py:meth:`.EntityList.append()` or 
+            :py:meth:`EntityList.extend()` instead.
         """
         return self._root["entities"]
 
@@ -462,8 +466,12 @@ def entities(self, value):
         elif isinstance(value, list):
             self._root["entities"] = EntityList(self, value)
         elif isinstance(value, EntityList):
-            # Just don't ask
-            self._root["entities"] = copy.deepcopy(value, memo={"new_parent": self})
+            # TODO: this is kinda wasteful, especially in the cases where we do
+            # blueprint.entities += [...]
+            # However, there's no way to distinguish the above case from a raw
+            # set, which is troublesome because entity lists in that case must
+            # be copied to avoid maximum confusion for everyone involved
+            self._root["entities"] = EntityList(self, value.data)
         else:
             raise TypeError("'entities' must be an EntityList, list, or None")
 

draftsman/classes/entitylist.py

@@ -128,13 +128,13 @@ def append(self, name, copy=True, merge=False, **kwargs):
 
     @utils.reissue_warnings
     def extend(self, entities, copy=True, merge=False):
-        # type: (List[Union[str, EntityLike]], bool, bool, **dict) -> None
+        # type: (List[Union[str, EntityLike]], bool, bool) -> None
         """
-        Extends the entity list with the list provided.
-        Functionally the same as appending one element at a time
+        Extends this list with the list provided. Computationally the same
+        as appending one element at a time. 
 
-        :param copy: Passed through to append for each element
-        :param merge: Passed through to append for each element
+        :param copy: Whether or not to insert a copy of each element.
+        :param merge: Whether or not to merge each element, if possible.
 
         :example: