diff --git a/databaseReset.py b/databaseReset.py index fa41a51..0c5c40f 100644 --- a/databaseReset.py +++ b/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() diff --git a/dump.py b/dump.py index 9206690..4464823 100644 --- a/dump.py +++ b/dump.py @@ -1,11 +1,15 @@ -# Mimic the sqlite3 console shell's .dump command -# Author: Paul Kippes +"""Used to create the SQL dump which mimics the import of cave and expo +data from files. -# Every identifier in sql is quoted based on a comment in sqlite -# 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." +Mimic the sqlite3 console shell's .dump command +Author: Paul Kippes + +Every identifier in sql is quoted based on a comment in sqlite +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): """ diff --git a/localsettingsWSL.py b/localsettingsWSL.py index 01133ba..0034fdd 100644 --- a/localsettingsWSL.py +++ b/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") diff --git a/logbooksdump.py b/logbooksdump.py index 4fdcf0c..6877afd 100644 --- a/logbooksdump.py +++ b/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 diff --git a/manage.py b/manage.py index f9726f9..0970f13 100644 --- a/manage.py +++ b/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") diff --git a/middleware.py b/middleware.py index 220027f..43f7328 100644 --- a/middleware.py +++ b/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): """ diff --git a/reset-django.py b/reset-django.py index 578506b..92af453 100644 --- a/reset-django.py +++ b/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. diff --git a/settings.py b/settings.py index 4ac2cc2..7ca6ec2 100644 --- a/settings.py +++ b/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'), diff --git a/urls.py b/urls.py index 02dddd0..3a252a9 100644 --- a/urls.py +++ b/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( , +, ) + +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: -# This is a "url dispatcher" - something needed by every web framework. -# url( , -# , ) - -# 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. +# Many of these patterns do not work because troggle spent many years broken and we have +# not yet restored all the functions. Some may have never been fully implemented in +# the first place and what they were intended to provide is obscure. actualurlpatterns = [ url(r'^troggle$', views_other.frontpage, name="frontpage"), diff --git a/utils.py b/utils.py index 967ffa4..8f30add 100644 --- a/utils.py +++ b/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