docstrings, and remove first newline

do-copyright.py

@@ -4,11 +4,10 @@ import os
 import sys, getopt
 import re
 
-#
-# Note: this is a mutliline regexp:
-#
-text = """
-/*
+"""
+ Note: this is technically used as a mutliline regexp
+"""
+text = """/*
  * (c) Copyright YEAR CORSIKA Project, corsika-project@lists.kit.edu
  *
  * See file AUTHORS for a list of contributors.
@@ -19,23 +18,49 @@ text = """
  */\n
 """
 
-Debug = 0 # 0: nothing, 1: checking, 2: filesystem
+"""
+Debug settings are 0: nothing, 1: checking, 2: filesystem
+"""
+Debug = 0 
 
 excludeDirs = ["ThirdParty", "git"]
 excludeFiles = ['PhysicalConstants.h','CorsikaFenvOSX.cc', 'sgn.h']
 
 extensions = [".cc", ".h", ".test"]
 
-justCheck = True # T: only checking, F: also changing files 
+"""
+justCheck: T: only checking, F: also changing files 
+"""
+justCheck = True
+"""
+foundMissing: global variable set to True in case of any needed action 
+"""
 foundMissing = False
 
-forYear="YEAR" # replace this with year via command line
+"""
+forYear: replace this with year for copyright notice via command line
+"""
+forYear="YEAR" 
 
 
 ###############################################
 #
-def checkNote(filename):
-    global foundMissing, justCheck, forYear
+def checkNote(filename, justCheck, forYear):
+    """
+    function to check, if the file 'filename' contains an exact copy
+    of the copyright notice defined above. 
+    The function also checks for eventual multiple (maybe conflicting) 
+    copyright notices in the same file. 
+    
+    If 'justCheck' is True, the file will never be changed, otherwise
+    the function will attempt to put the correct notice exactly once 
+    at the top of the file. The copyright YEAR will be replace with 
+    'forYear', e.g. forYear="2019" or forYear="2018-2020", etc.
+    
+    The global variable 'foundMissing' is set to True in the event 
+    where any changes are identified, BUT not implemented. 
+    """
+    global foundMissing
     
     if Debug>0:
         print ("***********************************************")
@@ -43,15 +68,16 @@ def checkNote(filename):
     
     startNote = []
     endNote = []
-
-    # read input file into lines
+    
+    """ read input file into lines """
     lines = []
     with open(filename, "r", encoding="utf-8") as file:
         for line in file.readlines():
             lines.append(line)            
         file.close()
-
-    searchStatus = 0 # 0:before comment block, #1 in comment block, #2 found copyright
+    
+    """ 0:before comment block, #1 in comment block, #2 found copyright """
+    searchStatus = 0 
     blockStart = 0
     for iLine in range(len(lines)):
         line = lines[iLine]
@@ -66,14 +92,14 @@ def checkNote(filename):
                 endNote.append(iLine)
             searchStatus = 0
         iLine += 1
-
+    
     if Debug>0:
         txt = "states: n=" + str(len(startNote))
         for i in range(len(startNote)):
             txt += ",  [" + str(startNote[i]) + "-" + str(endNote[i]) + "]"         
         print ("stats: " + txt)
-
-    # now check if first copyright notices is already identical...
+    
+    """ now check if first copyright notices is already identical... """
     isSame = False
     if len(startNote)>0: 
         isSame = True
@@ -82,39 +108,39 @@ def checkNote(filename):
             if startNote[0]+iLine >= len(lines):
                 isSame = False
                 break
-            regex = re.compile(re.escape(noteLines[iLine+1].strip(" \n")).replace('YEAR','....'))
+            regex = re.compile(re.escape(noteLines[iLine].strip(" \n")).replace('YEAR','....'))
             if not re.match(regex, lines[startNote[0]+iLine].strip(" \n")):
                 isSame = False
                 foundMissing = True
-                print ("needs update: " + filename + " new=\'" + noteLines[iLine+1] + "\' vs old=\'" + lines[startNote[0]+iLine].rstrip('\n') + "\'")
+                print ("needs update: " + filename + " new=\'" + noteLines[iLine] + "\' vs old=\'" + lines[startNote[0]+iLine].rstrip('\n') + "\'")
                 break
     if Debug>0:
         print ("isSame=" + str(isSame) + " " + str(len(startNote)))
     
-    # check if notice is the same, or we need to remove multiple notices...
+    """ check if notice is the same, or we need to remove multiple notices... """
     if isSame and len(startNote)<=1:
         return                
-
+    
     if (len(startNote)==0):
         print ("No copyright note in file: " + filename)
-
-    # either we found a file with no copyright, or with wrong copyright notice here
+    
+    """ either we found a file with no copyright, or with wrong copyright notice here """
     if justCheck:
         foundMissing = True
         return
     
-    # add (new) copyright notice here:
+    """ add (new) copyright notice here: """
     print ("File: " + filename + ", make copy to " + filename+".bak")
     os.rename(filename, filename+".bak")
-
+    
     with open(filename, "w") as file:
-
+        
         textReplace = re.sub(r"Copyright YEAR ", "Copyright " + forYear + " ", text)
         file.write(textReplace)
         
         skip = False
         for iLine in range(len(lines)):
-
+            
             inBlock = False
             for iBlock in range(len(startNote)):
                 if iLine>=startNote[iBlock] and iLine<=endNote[iBlock]:
@@ -124,8 +150,9 @@ def checkNote(filename):
 
             if inBlock:
                 continue
-            
-            if lines[iLine].strip() != "": # if line after comment is empty, also remove it
+
+            """ if line after comment is empty, also remove it """
+            if lines[iLine].strip() != "":
                 skip = False
                     
             if not skip:
@@ -136,10 +163,11 @@ def checkNote(filename):
 
 ###############################################
 #
-# check files: loops over list of files,
-# excludes if wished, process otherwise
-# 
-def next_file(dir_name, files):
+def next_file(dir_name, files, justCheck, forYear):
+    """
+    check files: loops over list of files,
+    excludes if wished, process otherwise
+    """
     for check in excludeDirs :
         if check in dir_name:
             if Debug>1:
@@ -160,15 +188,18 @@ def next_file(dir_name, files):
         if excludeThisFile:
             continue
         if file_extension in extensions:
-            checkNote(os.path.join(dir_name, check))
+            checkNote(os.path.join(dir_name, check), justCheck, forYear)
         else:
             if Debug>1:
                 print ("exclude-extension: " + os.path.join(dir_name, check))
 
                 
 ###############################################
-# the main program
+# 
 def main(argv):
+   """
+    the main program
+   """
    global justCheck, foundMissing, Debug, forYear
    justCheck = True
    Debug = 0
@@ -194,15 +225,19 @@ def main(argv):
        print ('Only checking. No changes. See \'do-copyright.py -h\' for options.')
          
    for root, dirs, files in os.walk('./'):
-       next_file(root, files)
+       next_file(root, files, justCheck, forYear)
 
     
 ###############################################
-# main entry point
+#
 if __name__ == "__main__":
+   """
+   main python entry point 
+   """
    main(sys.argv[1:])
 
    if justCheck and foundMissing:
-       sys.exit(-1) # found error
+       """ found any need for action """
+       sys.exit(-1)
    print ("Finished")
    sys.exit(0)