Add docstring and type-hinting to gui.cut_list module

docs/conf.py

@@ -94,6 +94,11 @@ def setup(app):
 
 html_logo = conf['html_logo']
 
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
 html_css_files = conf['html_css_files']
 
 extlinks = conf['ext']['extlinks']['extlinks']

osecore/gui/cut_list/__init__.py

@@ -1,10 +1,11 @@
 """Package for code relating to creating a cut list in the GUI.
 """
 from ._create_cut_list_task_panel import (
-    create_copy_cut_list_to_clipboard_task_panel,
+    CutListItem, create_copy_cut_list_to_clipboard_task_panel,
     create_save_cut_list_to_file_task_panel)
 
 __all__ = [
     'create_copy_cut_list_to_clipboard_task_panel',
-    'create_save_cut_list_to_file_task_panel'
+    'create_save_cut_list_to_file_task_panel',
+    'CutListItem'
 ]

osecore/gui/cut_list/_create_cut_list_task_panel/__init__.py

@@ -4,8 +4,10 @@
     create_copy_cut_list_to_clipboard_task_panel
 from .create_save_cut_list_to_file_task_panel import \
     create_save_cut_list_to_file_task_panel
+from .cut_list_item import CutListItem
 
 __all__ = [
     'create_copy_cut_list_to_clipboard_task_panel',
-    'create_save_cut_list_to_file_task_panel'
+    'create_save_cut_list_to_file_task_panel',
+    'CutListItem'
 ]

osecore/gui/cut_list/_create_cut_list_task_panel/create_copy_cut_list_to_clipboard_task_panel.py

@@ -1,11 +1,59 @@
+from typing import List, Optional
+
+from .cut_list_item import CutListItem
 from .cut_list_task_panel_factory import CutListTaskPanelFactory
 from .cut_list_task_type import CutListTaskType
+from .task_panel import CopyCutListToClipboardTaskPanel
 
 
 def create_copy_cut_list_to_clipboard_task_panel(
-        cut_list_items,
-        merge_cut_list_items_by_length=False,
-        note=None):
+        cut_list_items: List[CutListItem],
+        merge_cut_list_items_by_length: bool = False,
+        note: Optional[str] = None) -> CopyCutListToClipboardTaskPanel:
+    """Create a task panel to copy a cut-list to the user's clipboard.
+
+    **Simple Usage**
+
+    .. code-block:: python
+
+        cut_list = [
+            {'quantity': '1', 'description': 'Foo', 'length': '3 in'},
+            {'quantity': '1', 'description': 'Bar', 'length': '3 in'}]
+        panel = create_copy_cut_list_to_clipboard_task_panel(cut_list)
+        Gui.Control.showDialog(panel)
+
+    .. figure:: /_static/copy-cut-list-to-clipboard-task-panel.png
+       :alt: Copy Cut List to Clipboard Task Panel
+       :align: center
+
+       Copy Cut List to Clipboard Task Panel
+
+    **Merge Cut List Items by Length**
+
+    .. code-block:: python
+
+        cut_list = [
+            {'quantity': '1', 'description': 'Foo', 'length': '3 in'},
+            {'quantity': '1', 'description': 'Bar', 'length': '3 in'}]
+        panel = create_copy_cut_list_to_clipboard_task_panel(cut_list,
+            merge_cut_list_items_by_length=True)
+        Gui.Control.showDialog(panel)
+
+    .. figure:: /_static/copy-cut-list-to-clipboard-task-panel-merge-items.png
+       :alt: Copy Cut List to Clipboard Task Panel with Merged Items
+       :align: center
+
+       Copy Cut List to Clipboard Task Panel with Merged Items
+
+    :param cut_list_items: A cut list.
+    :type cut_list_items: List[CutListItem]
+    :param merge_cut_list_items_by_length: Whether to merge cut-list items by length, defaults to ``False``
+    :type merge_cut_list_items_by_length: bool, optional
+    :param note: A note to display underneath cut-list table, defaults to None
+    :type note: str, optional
+    :return: Copy Cut List to Clipboard Task Panel
+    :rtype: CopyCutListToClipboardTaskPanel
+    """
     factory = CutListTaskPanelFactory(
         cut_list_items,
         merge_cut_list=merge_cut_list_items_by_length,

osecore/gui/cut_list/_create_cut_list_task_panel/create_save_cut_list_to_file_task_panel.py

@@ -1,11 +1,59 @@
+from typing import List, Optional
+
+from .cut_list_item import CutListItem
 from .cut_list_task_panel_factory import CutListTaskPanelFactory
 from .cut_list_task_type import CutListTaskType
+from .task_panel import SaveCutListAsCsvTaskPanel
 
 
 def create_save_cut_list_to_file_task_panel(
-        cut_list_items,
-        merge_cut_list_items_by_length=False,
-        note=None):
+        cut_list_items: List[CutListItem],
+        merge_cut_list_items_by_length: bool = False,
+        note: Optional[str] = None) -> SaveCutListAsCsvTaskPanel:
+    """Create a task panel to save a cut-list to the user's filesystem.
+
+    **Simple Usage**
+
+    .. code-block:: python
+
+        cut_list = [
+            {'quantity': '1', 'description': 'Foo', 'length': '3 in'},
+            {'quantity': '1', 'description': 'Bar', 'length': '3 in'}]
+        panel = create_save_cut_list_to_file_task_panel(cut_list)
+        Gui.Control.showDialog(panel)
+
+    .. figure:: /_static/save-cut-list-to-file-task-panel.png
+       :alt: Save Cut List to File Task Panel
+       :align: center
+
+       Save Cut List to File Task Panel
+
+    **Merge Cut List Items by Length & Note**
+
+    .. code-block:: python
+
+        cut_list = [
+            {'quantity': '1', 'description': 'Foo', 'length': '3 in'},
+            {'quantity': '1', 'description': 'Bar', 'length': '3 in'}]
+        panel = create_save_cut_list_to_file_task_panel(cut_list,
+            merge_cut_list_items_by_length=True, note='example note')
+        Gui.Control.showDialog(panel)
+
+    .. figure:: /_static/save-cut-list-to-file-task-panel-merge-items-note.png
+       :alt: Save Cut List to File Task Panel with Merged Items & Note
+       :align: center
+
+       Save Cut List to File Task Panel with Merged Items & Note
+
+    :param cut_list_items: A cut list.
+    :type cut_list_items: List[CutListItem]
+    :param merge_cut_list_items_by_length: Whether to merge cut-list items by length, defaults to ``False``
+    :type merge_cut_list_items_by_length: bool, optional
+    :param note: A note to display underneath cut-list table, defaults to None
+    :type note: str, optional
+    :return: Save Cut List to File Task Panel
+    :rtype: SaveCutListAsCsvTaskPanel
+    """
     factory = CutListTaskPanelFactory(
         cut_list_items,
         merge_cut_list=merge_cut_list_items_by_length,

osecore/gui/cut_list/_create_cut_list_task_panel/cut_list_item.py

@@ -0,0 +1,17 @@
+from typing import NamedTuple
+
+
+"""TODO: Replace with ``TypedDict`` when no longer support <= Py 3.7.
+         See Also:
+            https://stackoverflow.com/a/54198204
+"""
+
+
+class CutListItem(NamedTuple):
+    """Represents an item in a cut-list.
+
+    Used for typing purposes only.
+    """
+    quantity: str
+    description: str
+    length: str