From 2a300d5d2f5a8cb6ef668f75237fe57a963708c3 Mon Sep 17 00:00:00 2001 From: Matthew Richards Date: Tue, 22 Sep 2020 12:47:03 +0000 Subject: [PATCH] #148: Add docstrings and general comments --- common/icat/helpers.py | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/common/icat/helpers.py b/common/icat/helpers.py index 9331e3fb..3a90abf1 100644 --- a/common/icat/helpers.py +++ b/common/icat/helpers.py @@ -302,9 +302,23 @@ def map_distinct_attributes_to_entity_names(self, distinct_fields): This function looks at a list of dot-separated fields and maps them to which entity they belong to - TODO - Add docstring - - TODO - Explain concept of base in docstring and why that key is always added + The result of this function will be a dictionary that has a data structure + similar to the example below. The values assigned to the 'base' key are the + fields that belong to the entity the request is being sent to (e.g. the base + values of `/users` would be fields belonging to the User entity). + + For distinct fields that are part of included entities (e.g. userGroups.id), it + is assumed that the relevant entities has been specified in an include filter. + This is checked, but only a warning is logged, + + Example return value: + `{'base': ['id', 'modTime'], 'userGroups': ['id', 'fullName'], + 'investigationUser': ['id', 'role']}` + + :param distinct_fields: List of fields that should be distinctive in the request + response, as per the distinct filters in the request + :type distinct_fields: :class:`list` + :return: Dictionary of fields, where the key denotes which entity they belong to """ # Mapping which entities have distinct fields @@ -313,11 +327,15 @@ def map_distinct_attributes_to_entity_names(self, distinct_fields): for field in distinct_fields: split_fields = field.split(".") + # Single element list means the field belongs to the entity which the + # request has been sent to if len(split_fields) == 1: # Conventional list assignment causes IndexError because -2 is out of # range of a list with a single element split_fields.insert(-2, "base") + # If a key doesn't exist in the dictionary, create it and assign an empty + # list to it try: distinct_field_dict[split_fields[-2]] except KeyError: @@ -329,7 +347,20 @@ def map_distinct_attributes_to_entity_names(self, distinct_fields): def prepare_distinct_fields_for_recursion(self, entity_name, distinct_fields): """ - TODO - Add docstring + Copy `distinct_fields` and move the data held in `entity_name` portion of the + dictionary to the "base" section of the dictionary. This function is called in + preparation for recursive calls occurring in entity_to_dict() + + See map_distinct_attribute_to_entity_names() for an explanation regarding + `distinct_fields` and its data structure + + :param entity_name: Name of the Python ICAT entity + :type entity_name: :class:`str` + :param distinct_fields: Names of fields in Python ICAT which should be outputted + in the response, separated by which entities they belong to as the keys + :type distinct_fields: :class:`dict` + :return: A copy of `distinct_fields`, with the data from the entity name put + into the base portion of the dictionary """ distinct_fields_copy = distinct_fields.copy()