Added type hints to library, add config

Author: twsl

mkdocs_git_authors_plugin/ci.py

@@ -6,16 +6,17 @@
 Taken from https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/blob/master/mkdocs_git_revision_date_localized_plugin/ci.py
 """
 
+import logging
 import os
 from contextlib import contextmanager
-import logging
 from pathlib import Path
-from typing import Union
+from typing import Any, Generator, Union
+
 from mkdocs_git_authors_plugin.git.command import GitCommand
 
 
 @contextmanager
-def working_directory(path: Union[str, Path]):
+def working_directory(path: Union[str, Path]) -> Generator[None, Any, None]:
     """
     Temporarily change working directory.
     A context manager which changes the working directory to the given
@@ -27,7 +28,7 @@ def working_directory(path: Union[str, Path]):
         # Do something in new directory
     # Back to old directory
     ```
-    """    
+    """
     origin = Path().absolute()
     try:
         os.chdir(path)

mkdocs_git_authors_plugin/config.py

@@ -0,0 +1,21 @@
+from mkdocs.config import config_options
+from mkdocs.config.base import Config
+
+
+class GitAuthorsPluginConfig(Config):
+    show_contribution = config_options.Type(bool, default=False)
+    show_line_count = config_options.Type(bool, default=False)
+    show_email_address = config_options.Type(bool, default=True)
+    href = config_options.Type(str, default="mailto:{email}")
+    count_empty_lines = config_options.Type(bool, default=True)
+    fallback_to_empty = config_options.Type(bool, default=False)
+    exclude = config_options.Type(list, default=[])
+    ignore_commits = config_options.Type(str, default="")
+    ignore_authors = config_options.Type(list, default=[])
+    enabled = config_options.Type(bool, default=True)
+    enabled_on_serve = config_options.Type(bool, default=True)
+    sort_authors_by = config_options.Type(str, default="name")
+    authorship_threshold_percent = config_options.Type(int, default=0)
+    strict = config_options.Type(bool, default=True)
+    # sort_authors_by_name = config_options.Type(bool, default=True)
+    # sort_reverse = config_options.Type(bool, default=False)

mkdocs_git_authors_plugin/git/author.py

@@ -1,16 +1,16 @@
-from .repo import AbstractRepoObject, Repo
-from .page import Page
-from .commit import Commit
+from typing import Dict, Union
 
-from typing import Dict
+from mkdocs_git_authors_plugin.git.commit import Commit
+from mkdocs_git_authors_plugin.git.page import Page
+from mkdocs_git_authors_plugin.git.repo import AbstractRepoObject, Repo
 
 
 class Author(AbstractRepoObject):
     """
     Abstraction of an author in the Git repository.
     """
 
-    def __init__(self, repo: Repo, name: str, email: str):
+    def __init__(self, repo: Repo, name: str, email: str) -> None:
         """
         Instantiate an Author.
 
@@ -24,7 +24,7 @@ def __init__(self, repo: Repo, name: str, email: str):
         self._email = email
         self._pages: Dict[str, dict] = dict()
 
-    def add_lines(self, page: Page, commit: Commit, lines: int = 1):
+    def add_lines(self, page: Page, commit: Commit, lines: int = 1) -> None:
         """
         Add line(s) in a given page/commit to the author's data.
 
@@ -42,7 +42,7 @@ def add_lines(self, page: Page, commit: Commit, lines: int = 1):
             entry["datetime"] = commit_dt
             entry["datetime_str"] = commit.datetime(str)
 
-    def contribution(self, path=None, _type=float):
+    def contribution(self, path=None, _type=float) -> Union[float, str]:
         """
         The author's relative contribution to a page or the repository.
 
@@ -60,17 +60,17 @@ def contribution(self, path=None, _type=float):
             formatted string or floating point number
         """
         lines = self.lines(path)
-        total_lines = (
+        total_lines: int = (
             self.page(path)["page"].total_lines() if path else self.repo().total_lines()
         )
 
         # Some pages are empty, that case contribution is 0 by default
         if total_lines == 0:
-            result = 0
+            result = 0.0
         else:
             result = lines / total_lines
 
-        if _type == float:
+        if _type is float:
             return result
         else:
             return str(round(result * 100, 2)) + "%"
@@ -87,10 +87,10 @@ def datetime(self, path, fmt=str):
             a formatted string (fmt=str)
             or a datetime.datetime object with tzinfo
         """
-        key = "datetime_str" if fmt == str else "datetime"
+        key = "datetime_str" if fmt is str else "datetime"
         return self.page(path).get(key)
 
-    def email(self):
+    def email(self) -> str:
         """
         The author's email address
 
@@ -101,7 +101,7 @@ def email(self):
         """
         return self._email
 
-    def lines(self, path=None):
+    def lines(self, path=None) -> int:
         """
         The author's total number of lines on a page or in the repository.
 
@@ -117,7 +117,7 @@ def lines(self, path=None):
         else:
             return sum([v["lines"] for v in self._pages.values()])
 
-    def name(self):
+    def name(self) -> str:
         """
         The author's full name
 
@@ -128,7 +128,7 @@ def name(self):
         """
         return self._name
 
-    def page(self, path, page=None):
+    def page(self, path, page=None) -> dict:
         """
         A dictionary with the author's contribution to a page.
 
@@ -154,7 +154,7 @@ def page(self, path, page=None):
         if not self._pages.get(path):
             self._pages[path] = {
                 "page": page or self.repo().page(path),
-                "lines": 0
+                "lines": 0,
                 # datetime and datetime_str will be populated later
             }
         return self._pages[path]

mkdocs_git_authors_plugin/git/command.py

@@ -1,4 +1,5 @@
 import subprocess
+from typing import List, Union
 
 
 class GitCommandError(Exception):
@@ -24,7 +25,7 @@ class GitCommand(object):
     In case of an error a verbose GitCommandError is raised.
     """
 
-    def __init__(self, command: str, args: list = []):
+    def __init__(self, command: str, args: List = []) -> None:
         """
         Initialize the GitCommand.
 
@@ -40,7 +41,7 @@ def __init__(self, command: str, args: list = []):
         self._stderr = None
         self._completed = False
 
-    def run(self):
+    def run(self) -> int:
         """
         Execute the configured Git command.
 
@@ -82,7 +83,7 @@ def run(self):
         self._completed = True
         return int(str(p.returncode))
 
-    def set_args(self, args: list):
+    def set_args(self, args: List) -> None:
         """
         Change the command arguments.
 
@@ -91,7 +92,7 @@ def set_args(self, args: list):
         """
         self._args = args
 
-    def set_command(self, command: str):
+    def set_command(self, command: str) -> None:
         """
         Change the Git command.
 
@@ -100,7 +101,7 @@ def set_command(self, command: str):
         """
         self._command = command
 
-    def stderr(self):
+    def stderr(self) -> Union[None, List[str]]:
         """
         Return the stderr output of the command as a string list.
 
@@ -113,7 +114,7 @@ def stderr(self):
             raise GitCommandError("Trying to read from uncompleted GitCommand")
         return self._stderr
 
-    def stdout(self):
+    def stdout(self) -> Union[None, List[str]]:
         """
         Return the stdout output of the command as a string list.
 

mkdocs_git_authors_plugin/git/commit.py

@@ -1,6 +1,8 @@
 import re
-from .repo import AbstractRepoObject, Repo
-from .. import util
+from typing import Union
+
+from mkdocs_git_authors_plugin import util
+from mkdocs_git_authors_plugin.git.repo import AbstractRepoObject, Repo
 
 
 class Commit(AbstractRepoObject):
@@ -58,7 +60,7 @@ def author(self):
         """
         return self._author
 
-    def datetime(self, _type=str):
+    def datetime(self, _type=str) -> Union[str, util.datetime]:
         """
         The commit's commit time.
 
@@ -71,4 +73,4 @@ def datetime(self, _type=str):
             The commit's commit time, either as a formatted string (_type=str)
             or as a datetime.datetime expression with tzinfo
         """
-        return self._datetime_string if _type == str else self._datetime
+        return self._datetime_string if _type is str else self._datetime

mkdocs_git_authors_plugin/git/page.py

@@ -1,11 +1,11 @@
-from pathlib import Path
-import re
 import logging
-from .repo import Repo, AbstractRepoObject
-from .command import GitCommand, GitCommandError
-
+import re
+from pathlib import Path
 from typing import List
 
+from mkdocs_git_authors_plugin.git.command import GitCommand, GitCommandError
+from mkdocs_git_authors_plugin.git.repo import AbstractRepoObject, Repo
+
 logger = logging.getLogger("mkdocs.plugins")
 
 
@@ -18,7 +18,7 @@ class Page(AbstractRepoObject):
     modified by that commit.
     """
 
-    def __init__(self, repo: Repo, path: Path, strict: bool):
+    def __init__(self, repo: Repo, path: Path, strict: bool) -> None:
         """
         Instantiate a Page object
 
@@ -32,7 +32,7 @@ def __init__(self, repo: Repo, path: Path, strict: bool):
         self._total_lines = 0
         self._authors: List[dict] = list()
         self._strict = strict
-        
+
         try:
             self._process_git_blame()
         except GitCommandError:
@@ -47,7 +47,7 @@ def __init__(self, repo: Repo, path: Path, strict: bool):
                     % path
                 )
 
-    def add_total_lines(self, cnt: int = 1):
+    def add_total_lines(self, cnt: int = 1) -> None:
         """
         Add line(s) to the count of total lines for the page.
 
@@ -56,7 +56,7 @@ def add_total_lines(self, cnt: int = 1):
         """
         self._total_lines += cnt
 
-    def get_authors(self):
+    def get_authors(self) -> List[dict]:
         """
         Return a sorted list of authors for the page
 
@@ -86,7 +86,7 @@ def get_authors(self):
                 ]
         return self._authors
 
-    def _process_git_blame(self):
+    def _process_git_blame(self) -> None:
         """
         Execute git blame and parse the results.
 
@@ -190,15 +190,17 @@ def _process_git_blame(self):
                     author_tz=commit_data.get("author-tz"),
                     summary=commit_data.get("summary"),
                 )
-                if commit.author().email() not in ignore_authors and (len(line) > 1 or self.repo().config("count_empty_lines")):
+                if commit.author().email() not in ignore_authors and (
+                    len(line) > 1 or self.repo().config("count_empty_lines")
+                ):
                     author = commit.author()
                     if author not in self._authors:
                         self._authors.append(author)
                     author.add_lines(self, commit)
                     self.add_total_lines()
                     self.repo().add_total_lines()
 
-    def path(self):
+    def path(self) -> Path:
         """
         The path to the markdown file.
 
@@ -209,7 +211,7 @@ def path(self):
         """
         return self._path
 
-    def total_lines(self):
+    def total_lines(self) -> int:
         """
         Total number of lines in the markdown source file.