From 0820d7c0dce82553348fbbd3bb34b288daae5480 Mon Sep 17 00:00:00 2001 From: Philip Sargent Date: Tue, 13 Apr 2021 01:37:42 +0100 Subject: [PATCH] Docstrings for all modules --- core/context.py | 8 ++++++++ core/forms.py | 4 ++++ core/middleware.py | 1 + core/unused.py | 4 ++-- core/views/caves.py | 7 ++++++- core/views/statistics.py | 3 +++ core/views/survex.py | 4 ++++ deprecations.txt | 6 ------ localsettingsWSL.py | 2 +- parsers/QMs.py | 1 + parsers/imports.py | 3 +++ parsers/logbooks.py | 6 ++++-- parsers/survex.py | 4 ++++ parsers/surveys.py | 4 ++++ requirements.txt | 10 +++++----- 15 files changed, 50 insertions(+), 17 deletions(-) diff --git a/core/context.py b/core/context.py index 908cd69..d2de27b 100644 --- a/core/context.py +++ b/core/context.py @@ -1,5 +1,13 @@ from django.conf import settings from troggle.core.models.troggle import Expedition +'''This is the only troglle-specific 'context processor' that troggle uses +in the processing of Django templates + +This seems to mean that every page produced has bundled in its context the complete 'settings' and +the expedition class object, so all templates can doe queries on Expedition. +https://betterprogramming.pub/django-quick-tips-context-processors-da74f887f1fc +''' + def troggle_context(request): return { 'settings':settings, 'Expedition':Expedition } \ No newline at end of file diff --git a/core/forms.py b/core/forms.py index 73d541a..f435e4c 100644 --- a/core/forms.py +++ b/core/forms.py @@ -11,6 +11,10 @@ from django.contrib.admin.widgets import AdminDateWidget from troggle.core.models.troggle import Person, PersonExpedition, Expedition from troggle.core.models.caves import Cave, LogbookEntry, QM, Entrance, CaveAndEntrance +'''These are all the Forms used by troggle +Some are not used and need renovating or destroying. +''' + class CaveForm(ModelForm): underground_description = forms.CharField(required = False, widget=forms.Textarea()) explorers = forms.CharField(required = False, widget=forms.Textarea()) diff --git a/core/middleware.py b/core/middleware.py index 56078a9..91e64ec 100644 --- a/core/middleware.py +++ b/core/middleware.py @@ -2,6 +2,7 @@ from django.conf import settings from django import http from django.urls import reverse, resolve,Resolver404 """Non-standard django middleware is loaded from this file. +It needs re-writing to be compatible with Django v2.0+ """ class SmartAppendSlashMiddleware(object): diff --git a/core/unused.py b/core/unused.py index c4e9ba3..76f55f4 100644 --- a/core/unused.py +++ b/core/unused.py @@ -5,8 +5,8 @@ import logging from django.conf import settings from django.shortcuts import render -"""Oddball mixture of critical, superfluous and useful functions which should -be re-located more sensibly to other modules: +"""Oddball mixture of apparently now superfluous functions which should +be deleted various HTML/wiki functions presumably for logbooks? diff --git a/core/views/caves.py b/core/views/caves.py index 8884d46..b4c2932 100644 --- a/core/views/caves.py +++ b/core/views/caves.py @@ -15,13 +15,18 @@ from django.shortcuts import get_object_or_404, render from django.core.exceptions import ObjectDoesNotExist, MultipleObjectsReturned import troggle.settings as settings -#import troggle.core.models as models from troggle.core.views import expo from troggle.core.models.troggle import Expedition, DataIssue from troggle.core.models.caves import CaveSlug, Cave, CaveAndEntrance, QM, EntranceSlug, Entrance, Area, SurvexStation, GetCaveLookup from troggle.core.forms import CaveForm, CaveAndEntranceFormSet, VersionControlCommentForm, EntranceForm, EntranceLetterForm from .login import login_required_if_public +'''Manages the complex procedures to assemble a cave description out of the compnoents +Manages the use of cavern to parse survex files to produce 3d and pos files + +Also generates the prospecting guide document. +''' + class MapLocations(object): p = [ ("laser.0_7", "BNase", "Reference", "Bräuning Nase laser point"), diff --git a/core/views/statistics.py b/core/views/statistics.py index fc62754..c317d43 100644 --- a/core/views/statistics.py +++ b/core/views/statistics.py @@ -17,6 +17,9 @@ from troggle.core.models.survex import SurvexBlock import troggle.settings as settings +'''Very simple report pages summarizing data about the whole set of expeditions and of +the status of data inconsistencies +''' def pathsreport(request): pathsdict = OrderedDict() diff --git a/core/views/survex.py b/core/views/survex.py index 2bcf79f..350c404 100644 --- a/core/views/survex.py +++ b/core/views/survex.py @@ -19,6 +19,10 @@ from troggle.core.models.survex import SurvexBlock, SurvexPersonRole, SurvexFile from troggle.core.models.caves import Cave, PersonTrip, LogbookEntry from troggle.parsers.people import GetPersonExpeditionNameLookup +'''Everything that views survexfiles +but also displays data on a cave or caves when there is ambiguity +''' + survexdatasetpath = Path(settings.SURVEX_DATA) survextemplatefile = """; *** THIS IS A TEMPLATE FILE NOT WHAT YOU MIGHT BE EXPECTING *** diff --git a/deprecations.txt b/deprecations.txt index 06c148a..e69de29 100644 --- a/deprecations.txt +++ b/deprecations.txt @@ -1,6 +0,0 @@ -/mnt/d/CUCC-Expo/t37/lib/python3.7/site-packages/django/db/models/sql/query.py:11: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3,and in 3.9 it will stop working - from collections import Counter, Iterator, Mapping, OrderedDict -/mnt/d/CUCC-Expo/t37/lib/python3.7/site-packages/django/db/models/sql/query.py:11: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3,and in 3.9 it will stop working - from collections import Counter, Iterator, Mapping, OrderedDict -/mnt/d/CUCC-Expo/t37/lib/python3.7/site-packages/django/core/paginator.py:126: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3,and in 3.9 it will stop working - class Page(collections.Sequence): diff --git a/localsettingsWSL.py b/localsettingsWSL.py index 7262ca0..76dc3aa 100644 --- a/localsettingsWSL.py +++ b/localsettingsWSL.py @@ -74,6 +74,7 @@ JSLIB_URL = urllib.parse.urljoin(URL_ROOT , '/javascript/') # used for CaveView PUBLIC_SITE = True DEBUG = True # Always keep this True, even when on public server. Otherwise NO USEFUL ERROR MESSAGES ! +CACHEDPAGES = True # experimental page cache for a handful of page types # executables: CAVERN = 'cavern' # for parsing .svx files and producing .3d files @@ -171,4 +172,3 @@ JSLIB_ROOT = os.fspath(JSLIB_ROOT) JSLIB_ROOT = os.fspath(JSLIB_ROOT) JSLIB_ROOT = os.fspath(JSLIB_ROOT) SURVEY_SCANS = os.fspath(SURVEY_SCANS) -print(" + finished importing troggle/localsettings.py") diff --git a/parsers/QMs.py b/parsers/QMs.py index 3a3e2bb..fe796a0 100644 --- a/parsers/QMs.py +++ b/parsers/QMs.py @@ -9,6 +9,7 @@ from troggle.core.models.troggle import DataIssue from troggle.core.models.caves import QM, Cave, LogbookEntry from troggle.core.utils import save_carefully +'''Reads the CSV files containg QMs for a select few caves''' def deleteQMs(): QM.objects.all().delete() diff --git a/parsers/imports.py b/parsers/imports.py index 5309065..bfafbfe 100644 --- a/parsers/imports.py +++ b/parsers/imports.py @@ -15,6 +15,9 @@ import troggle.parsers.surveys import troggle.parsers.logbooks import troggle.parsers.QMs +'''Master data importUsed only by databaseReset.py currently +''' + def import_caves(): print("-- Importing Caves to ",end="") print(django.db.connections.databases['default']['NAME']) diff --git a/parsers/logbooks.py b/parsers/logbooks.py index c24af07..51171d0 100644 --- a/parsers/logbooks.py +++ b/parsers/logbooks.py @@ -15,10 +15,12 @@ from troggle.core.utils import TROG, save_carefully from troggle.core.models.caves import Cave, LogbookEntry, PersonTrip, GetCaveLookup from parsers.people import GetPersonExpeditionNameLookup -# +''' +Parses and imports logbooks in all their wonderful confusion + # When we edit logbook entries, allow a "?" after any piece of data to say we've frigged it and # it can be checked up later from the hard-copy if necessary; or it's not possible to determin (name, trip place, etc) -# +''' # # the logbook loading section diff --git a/parsers/survex.py b/parsers/survex.py index 9d23cc8..ad6f27f 100644 --- a/parsers/survex.py +++ b/parsers/survex.py @@ -20,6 +20,10 @@ from troggle.core.views.caves import MapLocations from troggle.core.models.troggle import DataIssue, Expedition from troggle.core.models.survex import SurvexPersonRole, ScansFolder, SurvexDirectory, SurvexFile, SurvexBlock, SurvexStation +'''Imports the tree of survex files following form a defined root .svx file +It does also NOT scan the Loser repo for all the svx files - though it should ! +''' + survexblockroot = None ROOTBLOCK = "rootblock" METRESINFEET = 3.28084 diff --git a/parsers/surveys.py b/parsers/surveys.py index 66a3299..bba5d3f 100644 --- a/parsers/surveys.py +++ b/parsers/surveys.py @@ -15,6 +15,10 @@ from troggle.core.models.survex import SingleScan, ScansFolder, TunnelFile from troggle.core.models.troggle import DataIssue from troggle.core.utils import save_carefully +'''Scans through all the :drawings: repository looking +for tunnel and therion files +''' + def get_or_create_placeholder(year): """ All surveys must be related to a logbookentry. We don't have a way to diff --git a/requirements.txt b/requirements.txt index 5470f61..a7a7711 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,8 @@ confusable-homoglyphs==3.2.0 Django==2.2.19 -docutils==0.17 +docutils==0.14 gunicorn==20.1.0 -Pillow==8.2.0 -pytz==2021.1 -sqlparse==0.4.1 -Unidecode==1.2.0 +Pillow==5.4.1 +pytz==2019.1 +sqlparse==0.2.4 +Unidecode==1.0.23