updated comments

shared.py

@@ -8,17 +8,21 @@ from PIL import Image, ImageOps
 hostname = socket.gethostname()
 PROD_HOST="pa_web"
 
+# dict to store name of icon in icons.svg so we can use by referece in html
 ICON={}
 ICON["Import"]="import"
 ICON["Storage"]="db"
 ICON["Bin"]="trash"
 
+# check where we are running, if laptop, then run web server and db on localhost
 if hostname == "lappy":
     PA_JOB_MANAGER_HOST="localhost"
     DB_URL = 'postgresql+psycopg2://pa:for_now_pa@localhost:5432/pa'
+# if we dont set the env or we are explicitly DEV, run web server on localhost & db on mara (port 65432)
 elif 'FLASK_ENV' not in os.environ or os.environ['FLASK_ENV'] == "development":
     PA_JOB_MANAGER_HOST="localhost"
     DB_URL = 'postgresql+psycopg2://pa:for_now_pa@mara.ddp.net:65432/pa'
+# if we explicitly are on PROD, run web server on localhost (pa_web container) & db on mara (port 5432 on padb container)- only accessed via internal docker ports)
 elif os.environ['FLASK_ENV'] == "production":
     PA_JOB_MANAGER_HOST="localhost"
     DB_URL = 'postgresql+psycopg2://pa:for_now_pa@padb/pa'
@@ -26,10 +30,21 @@ else:
     print( "ERROR: I do not know which environment (development, etc.) and which DB (on which host to use)" )
     exit( -1 )
 
+# PORT number we connect to the pa_job_manager on - by default it runs on the
+# same host as the web manager, but it can run wherever (as long as the file
+# system is available in the same path)
 PA_JOB_MANAGER_PORT=55430
 
+# default thumbnail size (width and height) for images
 THUMBSIZE=256
 
+# Helper function used in html files to create a bootstrap'd select with options.  With:
+#    name: the data field in the submitted form
+#    selected: chooses the option that should be selected
+#    list: for the options
+#    js: optional extra javascript to run onChange (so far used to reset offset when choosing to change ordering of files being viewed)
+#    add_class: some class overrides, usually to format margins/padding/format/text size,etc.
+#    vals: in case the value is not the same as the name in the list provided... E.g. list={'yes', 'no'}, vals={1,0}
 def CreateSelect(name, selected, list, js="", add_class="", vals={} ):
     str  = f'<select id="{name}" name="{name}" class="{add_class} sm-txt bg-white text-info border-info border-1 p-1" onChange="{js};this.form.submit()">'
     for idx, el in enumerate(list):
@@ -42,6 +57,9 @@ def CreateSelect(name, selected, list, js="", add_class="", vals={} ):
     str += '</select>'
     return str
 
+# TODO: can this be collapsed into using above - probably if the 'selected' passed in was 'In Folder' or 'Flat View' -- but I think that isn't in a var???
+# Helper function used in html files to create a bootstrap'd select with options.  Same as CreateSelect() really, only contains
+# hard-coded True/False around the if selected part, but with string based "True"/"False" in the vals={}, and list has "In Folders", "Flat View"
 def CreateFoldersSelect(selected, add_class=""):
     str  = f'<select id="folders" name="folders" class="{add_class} sm-txt bg-white text-info border-info border-1 p-1" onChange="this.form.submit()">'
     # if selected is true, then folders == true, so make this the selected option
@@ -54,6 +72,8 @@ def CreateFoldersSelect(selected, add_class=""):
     str += '</select>'
     return str
 
+# wrapper function to return the path to an icon based on this objects type -
+# just for convenience/shortening in the html
 def LocationIcon(obj):
     return ICON[obj.in_dir.in_path.type.name]
 
@@ -79,6 +99,8 @@ def SymlinkName(ptype, path, file):
     return symlink
 
 
+# generates the thumbnail for an image - uses THUMBSIZE, and deals with non RGB images, and rotated images (based on exif)
+# returns data for thumbnail and original width and height, which gets stored in DB. Used when re-scaling viewed thumbs (refimgs on person page)
 def GenThumb(fname):
     try:
         im_orig = Image.open(fname)
@@ -98,6 +120,8 @@ def GenThumb(fname):
         print( f"GenThumb failed: {e}")
         return None, None, None
 
+# generate Face data (and location) - wrapper func of face_recognition library
+# used to store refimg data into the DB
 def GenFace(fname, model):
     img = face_recognition.load_image_file(fname)
     # TODO: change face_locations call basedon model