issue #37; starting to add docstrings to catalogitems/management/comm…

…ands modules

.gitignore

@@ -18,3 +18,4 @@ package.json
 *operacat_dabase
 *migrations*
 *media*
+.vscode*

operacat/catalogitems/apps.py

@@ -1,3 +1,8 @@
+"""auto-generated file from python manage.py startapp. 
+
+This is part of the wagtail infrastructure
+"""
+
 from django.apps import AppConfig
 
 

operacat/catalogitems/forms.py

@@ -3,6 +3,8 @@
 from .models import CatalogItemComment
 
 class CommentForm(forms.ModelForm):
+    """auto-generated form for comment posting on catalog item pages
+    """
     class Meta:
         model = CatalogItemComment
         fields = ['subject', 'comment_message']

operacat/catalogitems/management/commands/link_images_with_items.py

@@ -1,22 +1,51 @@
 
 import json
 from django.core.management.base import BaseCommand
-from catalogimage.models import CatalogImage
-from catalogitems.models import CatalogItemPage
+from operacat.catalogimage.models import CatalogImage
+from operacat.catalogitems.models import CatalogItemPage
 
 class Command(BaseCommand):
+    """a management command to interpret legacy data and link images to items
+
+    This class is necessary for migrating part of legacy data into the operacat
+    site.
+    """
     help = "Link images stored in site with the right catalog item page"
 
     def add_arguments(self, parser):
+        """the method that gets called to add parameter to the management command
+
+        It takes a parser object and adds a string type argument called
+        legacy_data_filepath
+        """
         parser.add_argument("legacy_data_filepath",
                             help="Path to legacy data JSON", type=str)
 
     def handle(self, *args, **options):
+        """the method that gets called to actually run the management command
+
+        It opens the legacy_data_filepath parameter and loads it into a JSON
+        object
+
+        Then it iterates through the list of dicts in the data and selects
+        out the image keys and item identifier key.
+
+        It finds the CatalogItemPage that matches the item identifier and
+        and if a matching CatalogItemPage can be found it continues. If not, it
+        sends an error message to stderr
+
+        It processes each item in the image to find the  matching CatalogImage
+        object in the system to retrieve the primary key/id attribute to
+        create stream_data dict item to append to stream_data list
+
+        At end, it sets the stream_data to the matching CatalogItemPage
+        images.stream_data attribute and saves the CatalogItemPage.
+        """
         data = json.load(open(options["legacy_data_filepath"], "r",
                               encoding="utf-8"))
-        for n in data:
-            if n.get("images", None):
-                cur = CatalogItemPage.objects.filter(title=n["item"])
+        for n_item in data:
+            if n_item.get("images", None):
+                cur = CatalogItemPage.objects.filter(title=n_item["item"])
                 stream_val = []
                 if cur.count() == 1:
                     cur = cur[0]

operacat/catalogitems/management/commands/load_complicated_snippets.py

@@ -7,14 +7,32 @@
 
 class Command(BaseCommand):
     """a management command to load migrate m2m field definition from legacy data
+
+    This class is necessary for adding places, authorOrResponsible,
+    recipientOrDedicatee and itemType information from legacy data to item pages
+    in the system
     """
     help = "Add m2m relation snippet information from legacy data to pages"
 
     def add_arguments(self, parser):
+        """the method that gets called to add parameter to the management command 
+
+        It takes a parser object and adds a string type argument called
+        legacy_data_filepath
+        """
         parser.add_argument("legacy_data_filepath",
                             help="Path to legacy data JSON", type=str)
 
     def _add_place_info(self, place_list, cur):
+        """a method to iterate a list of place names and add them to an item page
+
+        place_list = list of strings
+        cur = an instance of CatalogItemPage
+
+        This method iterates over a list of place names, finds the matching Place
+        snippet in the system and adds the the Place instance to the item_places
+        attribute of the relevant CatalogItemPage object
+        """
         for place in set(place_list):
             pl_name = place
             pl_record = Place.objects.filter(place_name=pl_name)
@@ -23,6 +41,15 @@ def _add_place_info(self, place_list, cur):
         return cur
 
     def _add_recipients(self, rec_list, cur):
+        """a method to iterate a list of recipients and add them to an item page
+
+        rec_list = list of dicts
+        cur = an instance of CatalogItemPage
+
+        This method iterates over a list of recipient dicts, finds the matching 
+        RecipientOrDedicatee snippet in the system and adds the
+        RecipientOrDedicatee instance to the item_places attribute of the relevant CatalogItemPage object
+        """
         for recipient in rec_list:
             re_name = recipient["name"]
             re_record = RecipientOrDedicatee.objects.\
@@ -51,6 +78,26 @@ def _add_item_types(self, type_list, cur):
         return cur
 
     def handle(self, *args, **options):
+        """the method that gets called to actually run the management command
+
+        It opens the legacy_data_filepath parameter and loads it into a JSON
+        object
+
+        Then it iterates through the list of dicts in the data and selects
+        out the author responsible, recipient dedicatee, place and item type
+        keys.
+
+        It finds the CatalogItemPage that matches the item identifier and
+        and if a matching CatalogItemPage can be found it continues. If not, it
+        sends an error message to stderr
+
+        It sends value of author responsible to private method _add_authors,
+        recipient dedicatee value to _add_recipients, place value
+        to _add_places, and item types to _add_item_types
+
+        At end, it sets the stream_data to the matching CatalogItemPage
+        images.stream_data attribute and saves the CatalogItemPage.
+        """
         data = json.load(open(options["legacy_data_filepath"], "r",
                               encoding="utf-8"))
         for n_thing in data:

operacat/catalogitems/management/commands/load_related_items.py

@@ -1,9 +1,10 @@
 
-from django.core.management.base import BaseCommand, CommandError
+from django.core.management.base import BaseCommand
 from catalogitems.models import CatalogItemPage
 import json
 from os.path import dirname, join
 
+
 class Command(BaseCommand):
     help = "Add related item info from legacy data to new OperaCat website"
 

operacat/catalogitems/templatetags/composer_tags.py

@@ -1,11 +1,25 @@
+"""this is the definition for composer tags for the site
+
+This is what enables the dynamically generated list of composers on
+the homepage of the site.
+"""
 
-from django import template
 from catalogitems.models import Composer
+from django import template
 
-register = template.Library()
 
-@register.inclusion_tag("catalogitems/tags/composer_tags.html", takes_context=True)
+REGISTER = template.Library()
+
+
+@REGISTER.inclusion_tag("catalogitems/tags/composer_tags.html",
+                        takes_context=True)
 def composers(context):
+    """a method to return a JSON object to iterate through in a html template
+
+    returns a dict with two keys:
+    - composers is a list of Composer objects,
+    - request is an http request object from current session request
+    """
     return {
         'composers': Composer.objects.all(),
         'request': context['request']