more code review and feature annotation

Author: richard-jones

docs/featuremap/types.csv

@@ -1,6 +1,7 @@
 Asset
 BackgroundTask
 Blueprint
+Build
 Config
 Crosswalk
 Data
@@ -11,13 +12,14 @@ Environment
 ExternalService
 Feature
 Fragment
+Framework
 Library
 Model
 Process
 Query
+Regex
 Schema
 Script
-SourceData
 Technology
 Template
 Test

docs/generated

@@ -1,4 +1,4 @@
-<!-- ~~LCC:SourceData~~ -->
+<!-- ~~LCCXML:Data~~ -->
 <subjects>
   <subject>
     <name>Agriculture</name>

lccSubjects.xml

@@ -2,7 +2,7 @@
 
 class Authorise(object):
     """
-    ~~Authorise:Feature->AuthNZ:Feature~~
+    ~~AuthNZ:Feature~~
     """
     @classmethod
     def has_role(cls, role, reference):

portality/authorise.py

@@ -1,3 +1,4 @@
+# ~~Constants:Config~~
 APPLICATION_STATUS_ACCEPTED = "accepted"
 APPLICATION_STATUS_REJECTED = "rejected"
 APPLICATION_STATUS_UPDATE_REQUEST = "update_request"

portality/constants.py

@@ -21,27 +21,49 @@
 
 @login_manager.user_loader
 def load_account_for_login_manager(userid):
+    """
+    ~~LoginManager:Feature->Account:Model~~
+    :param userid:
+    :return:
+    """
     from portality import models
     out = models.Account.pull(userid)
     return out
 
 
 def create_app():
+    """
+    ~~CreateApp:Framework->Flask:Technology~~
+    :return:
+    """
     app = Flask(__name__)
+    # ~~->AppSettings:Config~~
     configure_app(app)
+    #~~->ErrorHandler:Feature~~
     setup_error_logging(app)
+    #~~->Jinja2:Environment~~
     setup_jinja(app)
+    #~~->CrossrefXML:Feature~~
     app.config["LOAD_CROSSREF_THREAD"] = threading.Thread(target=load_crossref_schema, args=(app, ), daemon=True)
     app.config["LOAD_CROSSREF_THREAD"].start()
+    #~~->LoginManager:Feature~~
     login_manager.init_app(app)
+    #~~->CORS:Framework~~
     CORS(app)
+    #~~->APM:Feature~~
     initialise_apm(app)
+    #~~->DebugToolbar:Framework~~
     DebugToolbarExtension(app)
+    #~~->ProxyFix:Framework~~
     proxyfix(app)
+    #~~->CMS:Build~~
     build_statics(app)
     return app
 
 
+##################################################
+# Configure the App
+
 def configure_app(app):
     """
     Configure the DOAJ from:
@@ -104,7 +126,15 @@ def get_app_env(app):
     return env
 
 
+################################################
+# Crossref setup
+
 def load_crossref_schema(app):
+    """
+    ~~CrossrefXML:Feature->CrossrefXML:Schema~~
+    :param app:
+    :return:
+    """
     schema_path = app.config["SCHEMAS"].get("crossref")
 
     if not app.config.get("CROSSREF_SCHEMA"):
@@ -117,17 +147,17 @@ def load_crossref_schema(app):
                 message="There was an error attempting to load schema from " + schema_path, inner=e)
 
 
-def create_es_connection(app):
-    # temporary logging config for debugging index-per-type
-    #import logging
-    #esprit.raw.configure_logging(logging.DEBUG)
 
+############################################
+# Elasticsearch initialisation
+
+def create_es_connection(app):
+    # ~~ElasticConnection:Framework->Elasticsearch:Technology~~
     # make a connection to the index
     if app.config['ELASTIC_SEARCH_INDEX_PER_TYPE']:
         conn = esprit.raw.Connection(host=app.config['ELASTIC_SEARCH_HOST'], index='')
     else:
         conn = esprit.raw.Connection(app.config['ELASTIC_SEARCH_HOST'], app.config['ELASTIC_SEARCH_DB'])
-
     return conn
 
 
@@ -161,6 +191,12 @@ def put_mappings(conn, mappings):
 
 
 def initialise_index(app, conn):
+    """
+    ~~InitialiseIndex:Framework->Elasticsearch:Technology~~
+    :param app:
+    :param conn:
+    :return:
+    """
     if not app.config['INITIALISE_INDEX']:
         app.logger.warn('INITIALISE_INDEX config var is not True, initialise_index command cannot run')
         return
@@ -176,29 +212,56 @@ def initialise_index(app, conn):
     put_mappings(conn, mappings)
 
 
+##################################################
+# APM
+
 def initialise_apm(app):
+    """
+    ~~APM:Feature->ElasticAPM:Technology~~
+    :param app:
+    :return:
+    """
     if app.config.get('ENABLE_APM', False):
         from elasticapm.contrib.flask import ElasticAPM
         app.logger.info("Configuring Elastic APM")
         apm = ElasticAPM(app, logging=True)
 
 
+##################################################
+# proxyfix
+
 def proxyfix(app):
+    """
+    ~~ProxyFix:Framework~~
+    :param app:
+    :return:
+    """
     if app.config.get('PROXIED', False):
         from werkzeug.middleware.proxy_fix import ProxyFix
         app.wsgi_app = ProxyFix(app.wsgi_app, x_proto=1, x_host=1)
 
 
+##################################################
+# Jinja2
+
 def setup_jinja(app):
+    """
+    Jinja2:Environment->Jinja2:Technology
+    :param app:
+    :return:
+    """
     '''Add jinja extensions and other init-time config as needed.'''
 
     app.jinja_env.add_extension('jinja2.ext.do')
     app.jinja_env.add_extension('jinja2.ext.loopcontrols')
     app.jinja_env.globals['getattr'] = getattr
     app.jinja_env.globals['type'] = type
+    #~~->Constants:Config~~
     app.jinja_env.globals['constants'] = constants
+    #~~->Datasets:Data~~
     app.jinja_env.globals['datasets'] = datasets
     _load_data(app)
+    #~~->CMS:DataStore~~
     app.jinja_env.loader = FileSystemLoader([app.config['BASE_FILE_PATH'] + '/templates',
                                              os.path.dirname(app.config['BASE_FILE_PATH']) + '/cms/fragments'])
 
@@ -221,7 +284,16 @@ def _load_data(app):
         app.jinja_env.globals["data"][dataname] = data
 
 
+##################################################
+# Static Content
+
 def build_statics(app):
+    """
+    ~~CMS:Build->Fragments:Build~~
+    ~~->SASS:Build~~
+    :param app:
+    :return:
+    """
     if not app.config.get("DEBUG", False):
         return
     from portality.cms import build_fragments, build_sass

portality/core.py

@@ -24,6 +24,9 @@ class ElasticSearchWriteException(Exception):
 
 
 class DomainObject(UserDict, object):
+    """
+    ~~DomainObject:Model->Elasticsearch:Technology~~
+    """
     __type__ = None                                                       # set the type on the model that inherits this
 
     def __init__(self, **kwargs):
@@ -107,7 +110,14 @@ def last_updated_timestamp(self):
         return datetime.strptime(self.last_updated, "%Y-%m-%dT%H:%M:%SZ")
 
     def save(self, retries=0, back_off_factor=1, differentiate=False, blocking=False):
-
+        """
+        ~~->ReadOnlyMode:Feature~~
+        :param retries:
+        :param back_off_factor:
+        :param differentiate:
+        :param blocking:
+        :return:
+        """
         if app.config.get("READ_ONLY_MODE", False) and app.config.get("SCRIPTS_READ_ONLY_MODE", False):
             app.logger.warn("System is in READ-ONLY mode, save command cannot run")
             return
@@ -201,6 +211,13 @@ def save(self, retries=0, back_off_factor=1, differentiate=False, blocking=False
 
     @classmethod
     def bulk(cls, bibjson_list, idkey='id', refresh=False):
+        """
+        ~~->ReadOnlyMode:Feature~~
+        :param bibjson_list:
+        :param idkey:
+        :param refresh:
+        :return:
+        """
         if app.config.get("READ_ONLY_MODE", False) and app.config.get("SCRIPTS_READ_ONLY_MODE", False):
             app.logger.warn("System is in READ-ONLY mode, bulk command cannot run")
             return
@@ -216,6 +233,10 @@ def bulk(cls, bibjson_list, idkey='id', refresh=False):
 
     @classmethod
     def refresh(cls):
+        """
+        ~~->ReadOnlyMode:Feature~~
+        :return:
+        """
         if app.config.get("READ_ONLY_MODE", False) and app.config.get("SCRIPTS_READ_ONLY_MODE", False):
             app.logger.warn("System is in READ-ONLY mode, refresh command cannot run")
             return
@@ -826,12 +847,14 @@ class ESError(Exception):
 
 
 class Facetview2(object):
-
     """
-    {"query":{"filtered":{"filter":{"bool":{"must":[{"term":{"_type":"article"}}]}},"query":{"query_string":{"query":"richard","default_operator":"OR"}}}},"from":0,"size":10}
-    {"query":{"query_string":{"query":"richard","default_operator":"OR"}},"from":0,"size":10}
+    ~~SearchURLGenerator:Feature->Elasticsearch:Technology~~
     """
 
+    # Examples of queries
+    # {"query":{"filtered":{"filter":{"bool":{"must":[{"term":{"_type":"article"}}]}},"query":{"query_string":{"query":"richard","default_operator":"OR"}}}},"from":0,"size":10}
+    # {"query":{"query_string":{"query":"richard","default_operator":"OR"}},"from":0,"size":10}
+
     @staticmethod
     def make_term_filter(term, value):
         return {"term": {term: value}}

portality/dao.py

@@ -1,9 +1,17 @@
+"""
+~~DataSets:Data~~
+"""
+
 import pycountry
 from collections import OrderedDict
 
 
 def _generate_country_options():
-    """Gather the countries with 2-character codes"""
+    """
+    ~~->Countries:Data~~
+    ~~!Countries:Data->PyCountry:Technology~~
+    Gather the countries with 2-character codes
+    """
     country_options_ = [('', '')]
 
     for co in sorted(pycountry.countries, key=lambda x: x.name):
@@ -15,6 +23,11 @@ def _generate_country_options():
 
 
 def _generate_currency_options():
+    """
+    ~~->Currencies:Data~~
+    ~~!Currencies:Data->PyCountry:Technology~~
+    :return:
+    """
     currency_options_ = [(CURRENCY_DEFAULT, CURRENCY_DEFAULT)]
 
     for cu in sorted(pycountry.currencies, key=lambda x: x.name):
@@ -27,7 +40,11 @@ def _generate_currency_options():
 
 
 def _generate_language_options():
-    """ Gather the languages with 2-character codes (ISO 639-2b) """
+    """
+    ~~->Languages:Data~~
+    ~~!Languages:Data->PyCountry:Technology~~
+    Gather the languages with 2-character codes (ISO 639-2b)
+    """
     language_options_ = [('', '')]
     for l in sorted(pycountry.languages, key=lambda x: x.name):
         try:
@@ -39,7 +56,10 @@ def _generate_language_options():
 
 
 def _generate_license_options():
-    """ Licenses and their rights """
+    """
+    ~~->Licences:Data~~
+    Licenses and their rights
+    """
     licenses_ = {
         # The titles and types are made to match the current values of journals in the DOAJ.
         # DOAJ currently assumes type and title are the same.