Module documentation docstrings

databaseReset.py

@@ -6,6 +6,17 @@ import json
 import resource
 
 import settings
+""" Command-line utility for loading cave data files into troggle's database.
+
+The command line options select which combination of classes of data will be imported, 
+e.g. cave data, logbook data, cavers (people) data. The set of imports requested are put 
+into a job queue in a valid order, toegether with any necessary initialisation if it is
+a complete reset, and the queue is then executed.
+
+In future all these functions may be moved to a control panel webpage running within the
+troggle application.
+"""
+
 os.environ['PYTHONPATH'] = settings.PYTHON_PATH
 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'settings')
 
@@ -132,7 +143,7 @@ def memdumpsql(fn):
 
 class JobQueue():
     """A list of import operations to run. Always reports profile times
-    in the same order. 
+    of the import operations in the same order. 
     """
     
     def __init__(self,run):
@@ -154,7 +165,7 @@ class JobQueue():
         return True
 
     def loadprofiles(self):
-        """Load timings for previous runs from file
+        """Load timings for previous imports for each data import type
         """
         if os.path.isfile(self.tfile):
             try:
@@ -171,6 +182,8 @@ class JobQueue():
         return True
     
     def saveprofiles(self):
+        """Save timings for the set of imports just completed
+        """
         with open(self.tfile, 'w') as f:
             json.dump(self.results, f)     
         return True
@@ -212,10 +225,14 @@ class JobQueue():
             self.results[j].append(None) # append a placeholder
 
     def run_now_django_tests(self,n):
+        """Runs the standard django test harness system which is in troggle/core/TESTS/tests.py
+        """
         management.call_command('test', verbosity=n)
         django.db.close_old_connections() 
 
     def run(self):
+        """Initialises profile timings record, initiates relational database, runs the job queue saving the imported data as an SQL image and saves the timing profile data.
+        """
         self.loadprofiles()
         print("-- start   ",  django.db.connections.databases['default']['ENGINE'], django.db.connections.databases['default']['NAME'])
         self.runqonce()

dump.py

@@ -1,11 +1,15 @@
-# Mimic the sqlite3 console shell's .dump command
+"""Used to create the SQL dump which mimics the import of cave and expo
-# Author: Paul Kippes <kippesp@gmail.com>
+data from files.
 
-# Every identifier in sql is quoted based on a comment in sqlite
+Mimic the sqlite3 console shell's .dump command
-# documentation "SQLite adds new keywords from time to time when it
+Author: Paul Kippes <kippesp@gmail.com>
-# takes on new features. So to prevent your code from being broken by
+
-# future enhancements, you should normally quote any identifier that
+Every identifier in sql is quoted based on a comment in sqlite
-# is an English language word, even if you do not have to."
+documentation "SQLite adds new keywords from time to time when it
+takes on new features. So to prevent your code from being broken by
+future enhancements, you should normally quote any identifier that
+is an English language word, even if you do not have to."
+"""
 
 def _iterdump(connection):
     """

localsettingsWSL.py

@@ -1,6 +1,18 @@
 import sys
 import os
 import urllib.parse
+"""Settings for a troggle installation which may vary among different
+installations: for development or deployment, in a docker image or
+python virtual environment (venv), on ubuntu, debian or in Windows
+System for Linux (WSL), on the main server or in the potato hut,
+using SQLite or mariaDB.
+
+It sets the directory locations for the major parts of the system so
+that e.g. expofiles can be on a different filesystem.
+
+This file is included at the end of the main troggle/settings.py file so that
+it overwrites defaults in that file.
+"""
 
 # link 'localsettings.py' to localsettingsWSL.py for use on a Windows 10 machine running WSL1
 print(" * importing troggle/localsettings.py")

logbooksdump.py

@@ -3,6 +3,12 @@ import time
 import timeit
 
 import settings
+"""Two currently unused functions. To be re-engineered to produce a logbook file
+in canonical post-2010 Parseloghtmltxt() format after importing from one of the 
+older more artisanal formats which will then be retired. For example, 2003 used 
+a unique HTML format and we should regularise this and deprecate the unique parser
+code Parseloghtml03().
+"""
 os.environ['PYTHONPATH'] = settings.PYTHON_PATH
 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'settings')
 
@@ -34,6 +40,7 @@ def import_auto_logbooks():
                 print((os.path.join(root, filename)))
                 parsers.logbooks.parseAutoLogBookEntry(os.path.join(root, filename))
 
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
 #Temporary function until definitive source of data transfered.
 from django.template.defaultfilters import slugify
 from django.template import Context, loader

manage.py

@@ -1,6 +1,18 @@
 #!/usr/bin/env python
 import os
 import sys
+"""This file is the route to run the standard Django utilities on the command line.
+These ar ethe most useful for troggle:
+
+python manage.py test            --  runs the troggle test suite
+python manage.py test -v 3       --  runs the troggle test suite with more detailed output
+python manage.py -Wall check     --  runs the djang system package deprecation warnings
+python manage.py makemigrations  --  creates django db migrations files
+python manage.py inspectdb       --  creates datamodel documentaiton as python file  
+python manage.py check -v 3 --deploy           --  runs the django system security warnings
+python manage.py runserver  0.0.0.0:3777 -v 3  --  runs troggle SQLite webserver on port 3777
+python manage.py diffsettings | grep "###"     --  lists what is non-standard django in the settings
+"""
 
 if __name__ == "__main__":
     os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings")

middleware.py

@@ -2,6 +2,8 @@ from django.conf import settings
 from django import http
 from django.urls import reverse, resolve
 #from django.core.urlresolvers import resolve
+"""Non-standard django middleware is loaded from this file.
+"""
 
 class SmartAppendSlashMiddleware(object):
     """

reset-django.py

@@ -2,6 +2,14 @@ import os
 import shutil
 
 from pprint import pprint
+"""Cleans all django-created files and compiled python. Used by the
+pre-run.sh script which cleans and initialises everything before
+running:
+python databaseReset.py reset
+
+Downloaded (June 2020) from:
+https://groups.google.com/forum/#!topic/django-users/C8Q7CTpcChc
+"""
 
 # from https://groups.google.com/forum/#!topic/django-users/C8Q7CTpcChc
 # Just put it in the folder where manage.py file is and run it.

settings.py

@@ -31,7 +31,7 @@ BASE_DIR = os.path.dirname(os.path.dirname(__file__))
 
 # Django settings for troggle project.
 
-ALLOWED_HOSTS = ['expo.survex.com','localhost', '127.0.0.1']
+ALLOWED_HOSTS = ['expo.survex.com', '.survex.com', 'localhost', '127.0.0.1', '192.168.0.5' ]
 
 ADMINS = (
     # ('Your Name', 'your_email@domain.com'),

urls.py

@@ -10,16 +10,25 @@ from troggle.core.views_other import logbook_entry_suggestions
 from troggle.core.views_caves import ent, prospecting_image
 from troggle.core.views_statistics import pathsreport, stats
 from flatpages import views as flatviews
+"""This sets the actualurlpatterns[] and urlpatterns[] lists which django uses
+to resolve urls - in both directions as these are declarative. It runs
+django autodiscover() first:
+https://docs.djangoproject.com/en/1.11/ref/contrib/admin/#discovery-of-admin-files
+which may no longer be necessary in Django 1.11.29
 
+HOW THIS WORKS
+This is a "url dispatcher" - something needed by every web framework.
+url( <regular expression that matches the thing in the web browser>,
+<reference to python function in 'core' folder>, <optional name>)
+
+Django also provides the reverse function: given an an object, provide the URL
+which is vital to writing code for the webapp. So the URL dispatch is declarative.
+"""
 admin.autodiscover()
 
-#    HOW DOES THIS WORK:
+# Many of these patterns do not work because troggle spent many years broken and we have
-#    This is a "url dispatcher" - something needed by every web framework.
+# not yet restored all the functions. Some may have never been fully implemented in
-#    url( <regular expression that matches the thing in the web browser>,
+# the first place and what they were intended to provide is obscure.
-#         <reference to python function in 'core' folder>, <optional name>)
-
-#    Django also provides the reverse function: given an an object, provide the URL
-#    which is vital to writing code for the webapp. So the URL dispatch is declarative.
 
 actualurlpatterns = [
     url(r'^troggle$',    views_other.frontpage,      name="frontpage"),

utils.py

@@ -6,6 +6,18 @@ import logging
 from django.conf import settings
 from django.shortcuts import render
 from troggle.core.models_caves import CaveDescription
+"""Oddball mixture of critical, superfluous and useful functions which should 
+be re-located more sensibly to other modules:
+
+ChaosMonkey(n) - used by survex import to regenerate some .3d files
+save_carefully() - core function that saves troggle objects in the database
+
+various HTML/wiki functions presumably for logbooks?
+
+Use unknown:
+weighted_choice(lst)
+randomLogbookSentence()
+"""
 
 def ChaosMonkey(n):
     # returns True once every n calls - randomly