cleanup

organize imports, add some types

tildewiki/compilation.py

@@ -1,7 +1,7 @@
 import os
 import re
 from datetime import datetime
-from os.path import join as path_join
+from typing import Optional
 
 from markdown import markdown
 
@@ -20,50 +20,57 @@ def compile_wiki(source_path: str, dest_path: str) -> None:
     """
     last_compiled = '<p><em>last compiled: {}</em></p>'.format(datetime.utcnow())
 
-    header_content = compile_markdown(path_join(source_path, 'src/header.md'))
-    footer_content = last_compiled + compile_markdown(path_join(source_path, 'src/footer.md'))
+    header_content = compile_markdown(os.path.join(source_path, 'src/header.md'))
+    footer_content = last_compiled + compile_markdown(os.path.join(source_path, 'src/footer.md'))
 
     # TODO fix any links in header/footer to work with preview path
 
-    articles_root = path_join(source_path, 'src/articles')
+    articles_root = os.path.join(source_path, 'src/articles')
 
     toc_content = '{}\n<ul>'.format(update_title(header_content, 'table of contents'))
 
-    for root, dirs, files in os.walk(articles_root):
-        current_suffix = root.replace(articles_root, '')
+    for source_root, dirs, files in os.walk(articles_root):
+        current_suffix = source_root.replace(articles_root, '')
         if current_suffix and current_suffix[0] == '/':
             current_suffix = current_suffix[1:]
-        # TODO this is a bad var name since it might be publish path
-        preview_root = path_join(dest_path, current_suffix)
+
+        dest_root = os.path.join(dest_path, current_suffix)
 
         for directory in dirs:
-            os.mkdir(path_join(preview_root, directory))
+            os.mkdir(os.path.join(dest_root, directory))
 
         for source_filename in files:
-            source_file_path = path_join(root, source_filename)
+            source_file_path = os.path.join(source_root, source_filename)
             output = compile_source_file(
                 source_file_path,
                 header_content,
                 footer_content)
             dest_filename = source_filename.split('.')[0] + '.html'
             toc_content += '<li><a href="{}">{}</a></li>\n'.format(
-                path_join(current_suffix, dest_filename),
-                path_join(current_suffix,dest_filename.split('.')[0]))
-            with open(path_join(preview_root, dest_filename), 'w') as f:
+                os.path.join(current_suffix, dest_filename),
+                os.path.join(current_suffix,dest_filename.split('.')[0]))
+            with open(os.path.join(dest_root, dest_filename), 'w') as f:
                 f.write(output)
 
     toc_content += '\n</ul>'
-    with open(path_join(dest_path, 'toc.html'), 'w') as f:
+    with open(os.path.join(dest_path, 'toc.html'), 'w') as f:
         f.write(toc_content)
         f.write(footer_content)
 
-def slurp(file_path):
+def slurp(file_path:str) -> str:
+    """Convenience function for reading a file and returning its contents."""
     content = None
     with open(file_path, 'r') as f:
         content = f.read()
     return content
 
-def compile_source_file(source_file_path, header_content, footer_content):
+def compile_source_file(source_file_path:str, header_content:str, footer_content:str) -> str:
+    """Given a path to a source file, this function:
+    - picks an appropriate compiler for the file extension
+    - compiles the file
+    - sandwiches it between the provided header and footer content
+    - returns the constructed string
+    """
     if not os.path.isabs(source_file_path):
         raise ValueError(
             '{} is not an absolute path.'.format(source_file_path))
@@ -73,13 +80,11 @@ def compile_source_file(source_file_path, header_content, footer_content):
         compiler = compile_markdown
     elif source_file_path.endswith('.txt'):
         compiler = compile_plaintext
-    elif source_file_path.endswith('.html'):
+    else:
+        # this just copies through any files that we don't recognize as needing
+        # conversion.
         compiler = slurp
 
-    if compiler is None:
-        raise ValueError(
-            '{} is not a recognized file type.'.format(source_file_path))
-
     content = compiler(source_file_path)
 
     title = extract_title(content)
@@ -88,13 +93,13 @@ def compile_source_file(source_file_path, header_content, footer_content):
 
     return '{}\n{}\n{}'.format(header_content, content, footer_content)
 
-def update_title(content, title):
+def update_title(content:str, title:str) -> str:
     """Given a chunk of HTML, finds, updates, and returns the title element to
     be the given title. If there is no title element, the content is returned
     unmodified."""
     return re.sub(TITLE_RE, '<title>{}</title>'.format(title), content)
 
-def extract_title(content):
+def extract_title(content:str) -> Optional[str]:
     """Given a string of page content, look for a header in the first line.
     Returns it if found; returns None otherwise."""
     first_line = content.split('\n')[0]
@@ -103,12 +108,13 @@ def extract_title(content):
         return matches.groups()[1]
     return None
 
-def compile_markdown(source_file_path):
+def compile_markdown(source_file_path:str) -> str:
+    """Given a string of markdown, compiles it and returns the result."""
     return markdown(
         slurp(source_file_path),
         output_format='html5')
 
-def compile_plaintext(source_file_path):
+def compile_plaintext(source_file_path:str) -> str:
     output = '<p>\n'
     output += re.sub(
         DOUBLE_NEWLINE_RE,

tildewiki/main.py

@@ -3,19 +3,12 @@ import re
 from os.path import expanduser
 
 import click
-import pygit2
 from click import ClickException, Abort
 from click.types import Path
 from shutil import rmtree
 
-from .click_types import (
-    WikiRepo
-)
-
-from .compilation import (
-    compile_wiki
-)
-
+from .click_types import WikiRepo
+from .compilation import compile_wiki
 from . import git_wrapper as git
 
 # TODO support reading from env