create_asset_from_file: allow parent_node_id=None

Also added more documentation.

pillarsdk/nodes.py

@@ -1,4 +1,5 @@
 import json
+import copy
 
 import os.path
 
@@ -76,8 +77,23 @@ class Node(List, Find, Create, Post, Update, Delete, Replace):
 
     @classmethod
     def create_asset_from_file(cls, project_id, parent_node_id, asset_type, filename,
-                               always_create_new_node=False, api=None):
-        """Uploads the file to the Cloud and creates an asset node."""
+                               always_create_new_node=False,
+                               api=None):
+        """Uploads the file to the Cloud and creates an asset node.
+
+        If a node with the project, node_type (always 'asset') and name (always
+        basename of the given filename) exists, it will be updated (unless
+        always_create_new_node is True).
+
+        :param project_id: the project ID
+        :param parent_node_id: node ID to attach this asset node to. Can be None.
+        :param asset_type: 'image', 'file', 'video', etc.
+        :param filename: path of the file to upload. Must be readable.
+        :param always_create_new_node: when True, a new node is always created,
+            possibly with the same name & parent as an existing one.
+        :returns: the updated/created node
+        :rtype: Node
+        """
 
         api = api or Api.Default()
 
@@ -94,9 +110,10 @@ class Node(List, Find, Create, Post, Update, Delete, Replace):
         basic_properties = {
             'project': project_id,
             'node_type': 'asset',
-            'parent': parent_node_id,
             'name': os.path.basename(filename)
         }
+        if parent_node_id:
+            basic_properties['parent'] = parent_node_id
 
         if not always_create_new_node:
             # Try to find an existing one to see if there is anything to update.