#40849 Code cleanup pass (#6)

Added docstrings and general cleanup of prototype code.

app.py

@@ -7,17 +7,15 @@
 # By accessing, using, copying or modifying this work you indicate your 
 # agreement to the Shotgun Pipeline Toolkit Source Code License. All rights 
 # not expressly granted therein are reserved by Shotgun Software Inc.
-
-"""
-Multi Publish
-
-"""
 import os
 import sgtk
 
 class MultiPublish2(sgtk.platform.Application):
+    """
+    Main app class for publisher.
 
-    (VALIDATE, PUBLISH) = range(2)
+    Command registration and API methods.
+    """
 
     def init_app(self):
         """
@@ -26,16 +24,15 @@ def init_app(self):
         tk_multi_publish2 = self.import_module("tk_multi_publish2")
 
         # register command
-        cb = lambda : tk_multi_publish2.show_dialog(self)
-        menu_caption = "Publish..."
+        cb = lambda: tk_multi_publish2.show_dialog(self)
+        menu_caption = "Publish"
         menu_options = {
             "short_name": "publish",
-            "description": "Publishing of data into Shotgun",
-
+            "description": "Publishing of data to Shotgun",
             # dark themed icon for engines that recognize this format
             "icons": {
                 "dark": {
-                    "png": os.path.join(self.disk_location, "resources", "publish_menu_icon.png")
+                    "png": os.path.join(self.disk_location, "icon_256_dark.png")
                 }
             }
         }
@@ -49,7 +46,9 @@ def context_change_allowed(self):
         return True
 
     def destroy_app(self):
-
-        self.log_debug("Destroying tk-multi-publish")
+        """
+        Tear down the app
+        """
+        self.log_debug("Destroying tk-multi-publish2")
 
 

hooks/collector.py

@@ -13,31 +13,45 @@
 
 HookBaseClass = sgtk.get_hook_baseclass()
 
+
 class GenericSceneCollector(HookBaseClass):
     """
-    Collector that operates on the maya scene
+    A generic collector that handles files and general objects.
     """
 
     def process_current_scene(self, parent_item):
-        return None
+        """
+        Analyzes the current scene open in a DCC and parents a subtree of items
+        under the parent_item passed in.
+
+        :param parent_item: Root item instance
+        """
+        # default implementation does not do anything
 
     def process_file(self, parent_item, path):
+        """
+        Analyzes the given file and creates one or more items
+        to represent it.
 
+        :param parent_item: Root item instance
+        :param path: Path to analyze
+        :returns: The main item that was created
+        """
         file_name = os.path.basename(path)
         (file_name_no_ext, file_extension) = os.path.splitext(file_name)
 
         if file_extension in [".jpeg", ".jpg", ".png"]:
             file_item = parent_item.create_item("file.image", "Image File", file_name)
-            file_item.set_thumbnail(path)
-            file_item.set_icon(os.path.join(self.disk_location, "icons", "image.png"))
+            file_item.set_thumbnail_from_path(path)
+            file_item.set_icon_from_path(os.path.join(self.disk_location, "icons", "image.png"))
 
         elif file_extension in [".mov", ".mp4"]:
             file_item = parent_item.create_item("file.movie", "Movie File", file_name)
-            file_item.set_icon(os.path.join(self.disk_location, "icons", "quicktime.png"))
+            file_item.set_icon_from_path(os.path.join(self.disk_location, "icons", "quicktime.png"))
 
         else:
             file_item = parent_item.create_item("file", "Generic File", file_name)
-            file_item.set_icon(os.path.join(self.disk_location, "icons", "page.png"))
+            file_item.set_icon_from_path(os.path.join(self.disk_location, "icons", "page.png"))
 
         file_item.properties["extension"] = file_extension
         file_item.properties["path"] = path

hooks/file_publisher.py

@@ -15,27 +15,54 @@
 HookBaseClass = sgtk.get_hook_baseclass()
 
 
-class SceneHook(HookBaseClass):
+class GenericFilePublishPlugin(HookBaseClass):
     """
-    Testing the new awesome hooks
+    Plugin for creating generic publishes in Shotgun
     """
 
     @property
     def icon(self):
+        """
+        Path to an png icon on disk
+        """
         return os.path.join(self.disk_location, "icons", "shotgun.png")
 
     @property
-    def title(self):
+    def name(self):
+        """
+        One line display name describing the plugin
+        """
         return "Publish files to Shotgun"
 
     @property
-    def description_html(self):
+    def description(self):
+        """
+        Verbose, multi-line description of what the plugin does. This
+        can contain simple html for formatting.
+        """
         return """
         Publishes files to shotgun.
         """
 
     @property
     def settings(self):
+        """
+        Dictionary defining the settings that this plugin expects to recieve
+        through the settings parameter in the accept, validate, publish and
+        finalize methods.
+
+        A dictionary on the following form::
+
+            {
+                "Settings Name": {
+                    "type": "settings_type",
+                    "default": "default_value",
+                    "description": "One line description of the setting"
+            }
+
+        The type string should be one of the data types that toolkit accepts
+        as part of its environment configuration.
+        """
         return {
             "File Types": {
                 "type": "list",
@@ -57,11 +84,38 @@ def settings(self):
         }
 
     @property
-    def subscriptions(self):
+    def item_filters(self):
+        """
+        List of item types that this plugin is interested in.
+        Only items matching entries in this list will be presented
+        to the accept() method. Strings can contain glob patters
+        such as *, for example ["maya.*", "file.maya"]
+        """
         return ["file*"]
 
     def accept(self, log, settings, item):
-
+        """
+        Method called by the publisher to determine if an item
+        is of any interest to this plugin. Only items matching
+        the filters defined via the item_filters property will
+        be presented to this method.
+
+        A publish task will be generated for each item accepted
+        here. Returns a dictionary with the following booleans:
+
+            - accepted: Indicates if the plugin is interested in
+                        this value at all.
+            - required: If set to True, the publish task is
+                        required and cannot be disabled.
+            - enabled:  If True, the publish task will be
+                        enabled in the UI by default.
+
+        :param log: Logger to output feedback to.
+        :param settings: Dictionary of Settings. The keys are strings, matching the keys
+            returned in the settings property. The values are `Setting` instances.
+        :param item: Item to process
+        :returns: dictionary with boolean keys accepted, required and enabled
+        """
         extension = item.properties["extension"]
         if extension.startswith("."):
             extension = extension[1:]
@@ -89,10 +143,30 @@ def _get_matching_publish_type(self, extension, settings):
         return None
 
     def validate(self, log, settings, item):
+        """
+        Validates the given item to check that it is ok to publish.
+        Returns a boolean to indicate validity. Use the logger to
+        output further details around why validation has failed.
+
+        :param log: Logger to output feedback to.
+        :param settings: Dictionary of Settings. The keys are strings, matching the keys
+            returned in the settings property. The values are `Setting` instances.
+        :param item: Item to process
+        :returns: True if item is valid, False otherwise.
+        """
         return True
 
     def publish(self, log, settings, item):
-
+        """
+        Executes the publish logic for the given
+        item and settings. Use the logger to give
+        the user status updates.
+
+        :param log: Logger to output feedback to.
+        :param settings: Dictionary of Settings. The keys are strings, matching the keys
+            returned in the settings property. The values are `Setting` instances.
+        :param item: Item to process
+        """
         extension = item.properties["extension"]
         if extension.startswith("."):
             extension = extension[1:]
@@ -108,7 +182,7 @@ def publish(self, log, settings, item):
             "path": "file://%s" % item.properties["path"],
             "name": "%s%s" % (item.properties["prefix"], item.properties["extension"]),
             "version_number": item.properties["version"],
-            "thumbnail_path": item.get_thumbnail(),
+            "thumbnail_path": item.get_thumbnail_as_path(),
             "published_file_type": publish_type,
         }
 
@@ -119,6 +193,16 @@ def publish(self, log, settings, item):
 
 
     def finalize(self, log, settings, item):
+        """
+        Execute the finalization pass. This pass executes once
+        all the publish tasks have completed, and can for example
+        be used to version up files.
+
+        :param log: Logger to output feedback to.
+        :param settings: Dictionary of Settings. The keys are strings, matching the keys
+            returned in the settings property. The values are `Setting` instances.
+        :param item: Item to process
+        """
         pass