Documentation

_src/build.py

@@ -38,6 +38,7 @@ def namespace_from(extension: type) -> dict:
     """Generates global namespace for evaluation from provided class (extension)
     __builtins__ is empty by default, but can be overrided by extension
     """
+    
     namespace = {'__builtins__': {}}
     extension = vars(extension)
     for i in extension.keys():
@@ -46,15 +47,22 @@ def namespace_from(extension: type) -> dict:
     return namespace
 
 def evaluate_this(content: str, global_ns: dict) -> str:
+    """Finds some inline Python code in {braces} and evaluates it in-place.
+    global_ns is a dictionary of globals that it can use. It's recommended to use
+    namespace_from() to generate one.
+    """
+    
     return re.sub(r'\{([^\s}]+([^}]*[^\s}])?)\}', partial(evaluate, global_ns=global_ns), content)
 
 def evaluate(match: re.Match, global_ns: dict) -> str:
+    """Callable for re.sub, returns value of the last Python expression line,
+    executing all the other lines before.
+    """
+    
     match = match.group(1).split('\n')
-#    print('*','\n  '.join(match))
     # this trick let the functions in apis.py access our environment
     apis.environment = global_ns
-    # now let's execute the command!
-    # unfortunately we can't use 'return' in expressions
+    # we can't use 'return' in expressions
     # instead the last line will be evaluated and returned, the rest – executed
     local_ns = {}
     to_exec = '\n'.join(match[:-1])
@@ -69,9 +77,13 @@ def evaluate(match: re.Match, global_ns: dict) -> str:
         return '\n<a real error occured here>\n'
 
 def redirect(match: re.Match, domains: dict) -> str:
+    """Callable for re.sub, replaces urls to sites like youtube.com or twitter.com
+    with their respective privacy-respecting proxy services defined in config section
+    redirections
+    """
+    
     this_domain = match.group(2)
     if this_domain in domains:
-#        print('>',f'{this_domain} => {domains[this_domain]}')
         return match.group(1) + domains[this_domain] + match.group(3)
     else: return match.group(0)
 
@@ -193,7 +205,7 @@ if __name__ == '__main__':
         
         # convert absolute links to relative
         if path.endswith('.gmi'):
-            content = re.sub(r'=>(\s+)/(\S+)',
+            content = re.sub(r'^=>(\s+)/(\S+)',
                 lambda a: '=>'+a.group(1)+os.path.relpath(a.group(2), start=os.path.dirname(path)),
                 content)