inline docu

orvani.py

@@ -21,6 +21,14 @@ class OrvaniTag:
     }
 
     def __init__(self, path: str=CONTEXT_FILE, cache: str=CACHE_FILE, contexts=CTX):
+        """
+        Initialization
+
+        path (str): override default filename for folder context
+        cache (str): override default filename for cached index
+        contexts (dict): override the default contexts
+
+        """
         self.FILENAME = os.path.basename(path)
         self.CACHEFILE = cache
         self.INDEX = self.CTX.copy()
@@ -30,7 +38,13 @@ class OrvaniTag:
         self.__cd('')
 
     def __cd(self, path: str):
-        """change file context to subdirectory"""
+        """
+        Change folder context to other directory.
+        Checks if a folder context file exists and loads context DB.
+
+        path (str): path of the new folder context
+
+        """
         self.FILE = os.path.join(path, self.FILENAME)
         if os.path.isfile(self.FILE):
             try:
@@ -42,7 +56,10 @@ class OrvaniTag:
             self.DB = dict()
 
     def __save(self):
-        """save context file to current directory"""
+        """
+        Save current folder context to file
+
+        """
         try:
             with open(self.FILE, 'w+') as data:
                 yaml.dump(self.DB, data)
@@ -50,7 +67,12 @@ class OrvaniTag:
             print('File write error')
             
     def __context(self, argv) -> dict:
-        """create context for given filename"""
+        """
+        Creates a context entry for an existing file
+
+        argv (list): sets file contexts according to CTX schema
+        
+        """
         context = dict()
         for ctx in self.CTX.keys():
             context.update( { ctx : []})
@@ -64,6 +86,13 @@ class OrvaniTag:
         return context
 
     def add(self, file: str, *argv: str):
+        """
+        Add context to existing filename and saves local folder context file.
+
+        file (str): path to existing file
+        argv (list): context parameters passed to be added
+
+        """
         if os.path.isfile(file):
             if os.path.dirname(file):
                 self.__cd(os.path.dirname(file))
@@ -79,6 +108,13 @@ class OrvaniTag:
             self.__save()
 
     def remove(self, file: str, *argv: str):
+        """
+        Remove context of existing filename and saves changed folder context file
+
+        file (str): path to existing file
+        argv (list): context parameters to be removed
+
+        """
         if os.path.isfile(file):
             if os.path.dirname(file):
                 self.__cd(os.path.dirname(file))
@@ -92,6 +128,13 @@ class OrvaniTag:
             self.__save()
 
     def delete(self, file: str, fop:bool=False):
+        """
+        Deletes all entries of an existing file and optionally deletes the file
+
+        file (str): path to existing file
+        fop (bool): if True removes the referenced file
+
+        """
         if os.path.dirname(file):
             self.__cd(os.path.dirname(file))
         if fop:
@@ -102,6 +145,15 @@ class OrvaniTag:
         self.__save()
 
     def move(self, source: str, dest: str, retain: bool=False, fop: bool=True):
+        """
+        Copies or moves existing file with contexts to a new destination
+
+        source (str): existing source file
+        dest (str): the new file destination
+        retain (bool): if True then copies, if False then moves
+        fop (bool): if True also does the file operation, if False only moves context data
+
+        """
         if os.path.isfile(source) and os.path.isdir(os.path.dirname(dest)):
             sourcefolder = os.path.dirname(source)
             sourcefile = os.path.basename(source)
@@ -125,6 +177,12 @@ class OrvaniTag:
                     shutil.move(source, dest, copy_function=shutil.copy2)
             
     def purge(self, path: str=''):
+        """
+        Removes context data from folder if files do not exist
+
+        path (str): folder path
+
+        """
         if os.path.dirname(path):
             self.__cd(os.path.dirname(path))
         for file in self.DB.keys():
@@ -136,6 +194,17 @@ class OrvaniTag:
             os.remove(self.FILE)
 
     def list(self, search: str, path: str='./', filter=None, exact=True, recursive: bool=True, cache: bool=False):
+        """
+        Returns an index object with query results and optionally saves a cached index
+
+        search (str): the search query
+        path (str): the root context for the search and index
+        filter (str): limit the search to a context
+        exact (bool): exact search match if True, otherwise partial match
+        recursive (bool): if True also searches all subfolder contexts
+        cache (bool): if True loads index from cache file if exists, writes it if it doesn't exist
+
+        """
         if path == '':
             path = './'
         if not os.path.dirname(path):
@@ -178,6 +247,12 @@ class OrvaniTag:
         return result
         
     def __indexfolder(self, sub: str):
+        """
+        Indexes a folder context
+
+        sub (str): path of folder
+
+        """
         if os.path.dirname(sub):
             self.__cd(sub)
         if self.DB: