From 56dc99ae91486a711ad02705643bb22f2db64ad2 Mon Sep 17 00:00:00 2001 From: verbalhanglider Date: Fri, 26 May 2017 10:26:41 -0500 Subject: [PATCH] issue #37; starting to add docstrings to catalogitems/management/commands modules --- .gitignore | 1 + operacat/catalogitems/apps.py | 5 ++ operacat/catalogitems/forms.py | 2 + .../commands/link_images_with_items.py | 39 +++++++++++++-- .../commands/load_complicated_snippets.py | 47 +++++++++++++++++++ .../management/commands/load_related_items.py | 3 +- .../templatetags/composer_tags.py | 20 ++++++-- 7 files changed, 108 insertions(+), 9 deletions(-) diff --git a/.gitignore b/.gitignore index d4918ea..fb3d3cb 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ package.json *operacat_dabase *migrations* *media* +.vscode* diff --git a/operacat/catalogitems/apps.py b/operacat/catalogitems/apps.py index cb178ea..082084a 100644 --- a/operacat/catalogitems/apps.py +++ b/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 diff --git a/operacat/catalogitems/forms.py b/operacat/catalogitems/forms.py index f1a515c..8587727 100644 --- a/operacat/catalogitems/forms.py +++ b/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'] diff --git a/operacat/catalogitems/management/commands/link_images_with_items.py b/operacat/catalogitems/management/commands/link_images_with_items.py index c763282..acd4245 100644 --- a/operacat/catalogitems/management/commands/link_images_with_items.py +++ b/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] diff --git a/operacat/catalogitems/management/commands/load_complicated_snippets.py b/operacat/catalogitems/management/commands/load_complicated_snippets.py index 8b4dc9e..1d47eee 100644 --- a/operacat/catalogitems/management/commands/load_complicated_snippets.py +++ b/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: diff --git a/operacat/catalogitems/management/commands/load_related_items.py b/operacat/catalogitems/management/commands/load_related_items.py index a53ba02..1011537 100644 --- a/operacat/catalogitems/management/commands/load_related_items.py +++ b/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" diff --git a/operacat/catalogitems/templatetags/composer_tags.py b/operacat/catalogitems/templatetags/composer_tags.py index 263fcb1..10b1301 100644 --- a/operacat/catalogitems/templatetags/composer_tags.py +++ b/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']