OPEN-4515: Some additional code comments

LICENSE-EN.txt

@@ -15,7 +15,7 @@ held by the respective copyright holders as noted in those files. Users are aske
 
 MIT License
 
-Copyright (c) 2022 Government of Canada
+Copyright (c) 2026 Government of Canada
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
 associated documentation files (the "Software"), to deal in the Software without restriction,

LICENSE-FR.txt

@@ -20,7 +20,7 @@ dans ces fichiers. Nous demandons aux utilisateurs de lire les licences des tier
 
 Licence MIT
 
-(c) Droit d'auteur – Gouvernement du Canada, 2022
+(c) Droit d'auteur – Gouvernement du Canada, 2026
 
 La présente autorise toute personne d'obtenir gratuitement une copie du présent logiciel et des
 documents connexes (le « logiciel »), de traiter le logiciel sans restriction, y compris, mais sans

changes/62.changes

@@ -0,0 +1 @@
+Added additional comments to the core search application code and in a few cases removed dead or commented code. No functoinal changes.

oc_search/settings-sample.py

@@ -42,8 +42,9 @@
     'search',
 ]
 
-## Optional applications
+## Optional applications - this will be removed from search soon
 # 'ramp',
+
 MIDDLEWARE = [
     "corsheaders.middleware.CorsMiddleware",
     'django.middleware.security.SecurityMiddleware',
@@ -59,6 +60,8 @@
     'oc_search.middleware.CanadaBilingualMiddleware'
 ]
 
+# General web app settings
+
 CORS_ALLOW_ALL_ORIGINS = True
 CORS_REPLACE_HTTPS_REFERER = True
 SECURE_REFERRER_POLICY = 'unsafe-url'
@@ -67,6 +70,10 @@
 
 STATIC_ROOT = os.path.join(BASE_DIR, 'static')
 
+WSGI_APPLICATION = 'oc_search.wsgi.application'
+
+JSON_DOWNLOADS_ALLOWED = False
+
 # Static files (CSS, JavaScript, Images)
 # https://docs.djangoproject.com/en/3.0/howto/static-files/
 
@@ -76,7 +83,6 @@
     ('search_snippets', os.path.join(BASE_DIR, 'search', 'templates', 'snippets')),
     ('cache', os.path.join(BASE_DIR, 'cache')),
 ]
-# ('ramp', os.path.join(BASE_DIR, 'ramp', 'viewer')),
 
 TEMPLATES = [
     {
@@ -95,8 +101,8 @@
     },
 ]
 
-WSGI_APPLICATION = 'oc_search.wsgi.application'
-
+# Optional templates for Geoviewer - should be deprecated soon
+# ('ramp', os.path.join(BASE_DIR, 'ramp', 'viewer')),
 
 # Database
 # https://docs.djangoproject.com/en/3.0/ref/settings/#databases
@@ -125,8 +131,6 @@
 #     }
 # }
 
-JSON_DOWNLOADS_ALLOWED = False
-
 # Password validation
 # https://docs.djangoproject.com/en/3.0/ref/settings/#auth-password-validators
 
@@ -188,6 +192,7 @@
         'level': 'INFO',
     },
 }
+
 # Django Cache settings
 
 CACHES = {
@@ -270,17 +275,20 @@
     'table', 'thead', 'th', 'tr', 'tbody', 'td'
 ]
 MARKDOWN_FILTER_EXTRAS = ["tables", "break-on-newline"]
+
 # These are IN ADDITION to the attributes defined in leach.sanitizer.ALLOWED_ATTRIBUTES
+
 MARKDOWN_FILTER_ALLOWED_ATTRIBUTES = {'span': ['title', 'class'], "a": ["href", "title", "rel"]}
 
+# Analytics options used by the open canada site
+
 ADOBE_ANALYTICS_URL = ''
 GOOGLE_ANALYTICS_GTM_ID = ''
 GOOGLE_ANALYTICS_PROPERTY_ID = ''
 GOOGLE_ANALYTICS_GA4_ID = ''
 
-IMPORT_EXPORT_USE_TRANSACTIONS = False
+# Geoviewer Settings specifically for the Open Data Custom search - still required after RAMP app is removed
 
-# Geoviewer Settings specifically for the Open Data Custom search
 OPEN_DATA_SOLR_SERVER_URL = "http://localhost:8983/solr"
 OPEN_DATA_CORE = "search_opendata"
 OPEN_DATA_BASE_URL_EN = "https://open.canada.ca/data/en/dataset/"
@@ -290,7 +298,6 @@
 OPEN_DATA_HOST_EN = "https://open.canada.ca"
 OPEN_DATA_HOST_FR = "https://ouvert.canada.ca"
 
-
 # Celery Congifuration
 
 CELERY_BROKER_URL = 'redis://:<redis_password>@localhost:6379/0'

oc_search/urls.py

@@ -27,11 +27,7 @@
     path('search/admin/', admin.site.urls),
 ]
 
-# urlpatterns += [
-#     path('searchform/<str:lang>/', include('search.urls')),
-#     path('rechercherformulaire/<str:lang>/', include('search.urls')),
-# ]
-
+# URLs for when Search is configured to use the URL path to determine language of web page 
 if settings.SEARCH_LANG_USE_PATH:
     urlpatterns += [
         path('', DefaultView.as_view(), name="HomePage"),
@@ -68,6 +64,8 @@
             path('search/<str:lang>/<str:search_type>', SearchFormView.as_view(), name="search_form"),
             path('rechercher/<str:lang>/<str:search_type>', SearchFormView.as_view(), name="search_form"),
         ]
+
+# URLs to use when Search is configured to use the hostname to determine the language of the webpage IE open.canada.ca vs ouvert.canada.ca
 else:
     urlpatterns += [
         path('', DefaultView.as_view(), name="HomePage"),

search/admin.py

@@ -5,7 +5,6 @@
 
 # -- Searches ---
 
-
 class SearchAdmin(admin.ModelAdmin):
 
     list_display = ['search_id', 'label_en', 'solr_core_name']
@@ -28,8 +27,7 @@ class SearchAdmin(admin.ModelAdmin):
         ('More-like-this', {'fields': ('mlt_enabled', 'mlt_items')})
     )
 
-    # -- Fields ---
-
+# -- Fields ---
 
 def make_facet_field(modeladmn, request, queryset):
     queryset.update(is_search_facet=True)

search/extras/About_Extras.md

@@ -0,0 +1,5 @@
+This directory can be used to hold any extra files or data used by custom searches that does not
+fit into the usual custom search format. It allows non-standard files to be distributed with
+a custom search.  
+
+Most proactive disclosure searches did not use this feature

search/models/custom/readme.md

@@ -1,3 +1,4 @@
-This directory holds custom Django database models used by custom searches. These models are dynamically loaded
+This directory holds custom Django database models to be added to Django search application by custom searches. 
+These models are dynamically loaded into the search application but are not automatically migrated.
 
-into the search application but are not automatically migrated.
+Use the standard Django database migration commands to add these models to the database.

search/query.py

@@ -48,7 +48,8 @@ def uuid_pattern(version):
 
 
 def calc_pagination_range(num_found: int, pagesize, current_page, delta=2):
-    # @TODO This is not very efficient - could be refactored
+    """ Calculate pagination values based on provided values """
+
     pages = int(ceil(num_found / pagesize))
     if current_page > pages:
         current_page = pages
@@ -96,7 +97,7 @@ def calc_starting_row(page_num: str, rows_per_page=10):
 
 
 def get_search_terms(search_text: str):
-    # Get any search terms
+    """ Tokenize search terms"""
 
     tr = RegexpTokenizer(r'[^"\s]\S*|".+?"', gaps=False)
 
@@ -110,6 +111,8 @@ def get_search_terms(search_text: str):
 
 
 def get_query_fields(query_lang: str, fields: dict):
+    """ Return a language specific list of query fields for a search """
+
     qf = ['id']
     for f in fields:
         if fields[f].solr_field_lang in [query_lang, 'bi']:
@@ -130,6 +133,7 @@ def get_query_fields(query_lang: str, fields: dict):
 
 
 def get_mlt_fields(request: HttpRequest, fields: dict):
+    """ Return a language specific list of query fields for a more-like-this search """
     qf = ['id']
     for f in fields:
         if fields[f].solr_field_lang in [request.LANGUAGE_CODE, 'bi']:
@@ -210,16 +214,19 @@ def create_solr_query(request: HttpRequest, search: Search, fields: dict, Codes:
                     known_fields[request_field] = keys[request_field][0].split('|')
 
         # If sort not specified in the request, then use the default
+
         if 'sort' not in solr_query:
             solr_query['sort'] = default_sort
 
         # Sometimes, the sort order will be forced to the default value
+
         if override_sort:
             solr_query['sort'] = default_sort
 
         solr_query['q.op'] = search.solr_default_op
 
     # Create a Solr query field list based on the Fields Model. Expand the field list where needed
+
     solr_query['qf'] = get_query_fields(request.LANGUAGE_CODE, fields)
 
     if export:
@@ -238,6 +245,7 @@ def create_solr_query(request: HttpRequest, search: Search, fields: dict, Codes:
         solr_query['fl'] = ",".join(ef)
     else:
         solr_query['fl'] = ",".join(solr_query['qf'])
+
     if not export:
         solr_query['start'] = start_row
         solr_query['rows'] = rows
@@ -263,7 +271,8 @@ def create_solr_query(request: HttpRequest, search: Search, fields: dict, Codes:
             'hl.highlightMultiTerm': True,
         })
 
-    # Set a default sort order
+    # Set a default sort order if one not included in the query
+
     if 'sort' not in solr_query:
         solr_query['sort'] = 'score desc'
 
@@ -288,14 +297,19 @@ def create_solr_query(request: HttpRequest, search: Search, fields: dict, Codes:
                 ff.append(facet)
         solr_query['fq'] = fq
         solr_query['facet.field'] = ff
+
     if export and solr_query['sort'] == "score desc":
         solr_query['sort'] = "id asc"
+
     if search.solr_debugging:
         solr_query['debugQuery'] = True
+
     return solr_query
 
 
 def create_solr_mlt_query(request: HttpRequest, search: Search, fields: dict, start_row: int, record_id: str):
+    """ Create a Solr More-like-this query """
+
     solr_query = {
         'q': 'id:"{0}"'.format(record_id),
         'mlt': True,
@@ -312,10 +326,12 @@ def create_solr_mlt_query(request: HttpRequest, search: Search, fields: dict, st
     }
     return solr_query
 
+
 def create_post_solr_query(request: HttpRequest, search: Search, fields: dict, Codes: dict, facets: list,
                            start_row: int = 0, rows: int = 10, default_sort='score desc',  override_sort=False, 
                            is_export: bool = False, reset_filters: bool = False):
-
+    """ Create a Solr query based an an HTTP POST form request """
+
     # Look for known fields in the POST request
     known_fields = {}
 
@@ -390,6 +406,7 @@ def create_post_solr_query(request: HttpRequest, search: Search, fields: dict, C
         solr_query['q.op'] = search.solr_default_op
 
         # Create a Solr query field list based on the Fields Model. Expand the field list where needed
+
         solr_query['qf'] = get_query_fields(request.LANGUAGE_CODE, fields)
 
         if not is_export:

search/templatetags/search_extras.py

@@ -252,7 +252,6 @@ def add_str(value: str, arg1: str):
     return value + arg1
 
 
-
 @register.filter('replace_pageno')
 def trim_left(value: str, arg: int):
     return value.replace("__page__", str(arg))
@@ -276,6 +275,7 @@ def ds_status_label(value: str):
 def int_format(value: int, formatstr: str):
     return formatstr.format(value)
 
+
 @register.filter('normailize_id_value')
 def normailize_id_value(value: str):
     return value.replace(" ", "_").replace('é', 'e').replace('à', 'a')