OO refactoring and git-blame preloading

README.md

@@ -3,7 +3,7 @@
 ![PyPI](https://img.shields.io/pypi/v/mkdocs-git-authors-plugin)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-git-authors-plugin)
 [![codecov](https://codecov.io/gh/timvink/mkdocs-git-authors-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/timvink/mkdocs-git-authors-plugin)
- 
+
 # mkdocs-git-authors-plugin
 
 [MkDocs](https://www.mkdocs.org/) plugin to display git authors of a markdown page:
@@ -39,7 +39,7 @@ plugins:
 
 ### In markdown pages
 
-You can use ``{{ git_authors_summary }}`` to insert a summary of the authors of a page. Authors are sorted by their name and have a `mailto:` link with their email. 
+You can use ``{{ git_authors_summary }}`` to insert a summary of the authors of a page. Authors are sorted by their name and have a `mailto:` link with their email.
 
 An example output:
 
@@ -57,7 +57,7 @@ no supported themes *yet*.
 
 ### Customizing existing themes
 
-[MkDocs](https://www.mkdocs.org/) offers possibilities to [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme). 
+[MkDocs](https://www.mkdocs.org/) offers possibilities to [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme).
 
 As an example, if you use [mkdocs-material](https://github.com/squidfunk/mkdocs-material) you can easily implement git-authors by [overriding a template block](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks):
 
@@ -134,6 +134,13 @@ Example output:
 * Authors: [John Doe](#) (33.33%), [Jane Doe](#) (66.67%) *(more than one author)*
 * Authors: [John Doe](#) *(one author)*
 
+### `uncommitted_name` and `uncommitted_email`
+
+Lines that `git blame` consideres uncommitted can't be attributed to an author,
+therefore they are assigned to a virtual author `Uncommitted` with a pseudo
+email address of `#`. These values can be changed with the options
+`uncommitted_name` (default “Uncommitted”) and `uncommitted_email` (default “#”).
+
 ### Aggregating Authors
 
 In some repositories authors may have committed with differing name/email combinations.
@@ -150,4 +157,3 @@ Jane Doe <jane.doe@company.com> <jane.doe@private-email.com>
 This will map commits made with the `private-email.com` to the company address. For more details
 and further options (e.g. mapping between different names or misspellings etc. see the
 [git-blame documentation](https://git-scm.com/docs/git-blame#_mapping_authors).
-

mkdocs_git_authors_plugin/plugin.py

@@ -1,15 +1,81 @@
 import re
 from mkdocs.config import config_options
 from mkdocs.plugins import BasePlugin
-from .util import Util
+from .repo import Repo
 
 class GitAuthorsPlugin(BasePlugin):
     config_scheme = (
         ('show_contribution', config_options.Type(bool, default=False)),
+        ('show_lines', config_options.Type(bool, default=False)),
+        ('count_empty_lines', config_options.Type(bool, default=True)),
+        ('label_lines', config_options.Type(str, default='lines')),
+        ('sort_by', config_options.Choice(
+            ['name', 'contribution'], default='name')
+        ),
+        ('sort_reverse', config_options.Type(bool, default=False)),
+        ('uncommitted_name', config_options.Type(str, default='Uncommitted')),
+        ('uncommitted_email', config_options.Type(str, default='#'))
     )
 
     def __init__(self):
-        self.util = Util()
+        self._repo = Repo()
+
+    def on_config(self, config, **kwargs):
+        """
+        Store the plugin configuration in the Repo object.
+
+        This is only the dictionary with the plugin configuration,
+        not the global config which is passed to the various event handlers.
+        """
+        self.repo().set_config(self.config)
+
+    def on_files(self, files, **kwargs):
+        """
+        Preprocess all markdown pages in the project
+
+        This populates all the lines and total_lines properties
+        of the pages and the repository, so the total
+        contribution of an author to the repository can be
+        retrieved on *any* Markdown page.
+        """
+        for file in files:
+            path = file.abs_src_path
+            if path.endswith('.md'):
+                _ = self.repo().page(path)
+
+    def on_page_content(self, html, page, config, files, **kwargs):
+        """
+        Replace jinja tag {{ git_authors_list }} in HTML.
+
+        The page_content event is called after the Markdown text is
+        rendered to HTML (but before being passed to a template) and
+        can be used to alter the HTML body of the page.
+
+        https://www.mkdocs.org/user-guide/plugins/#on_page_content
+
+        We replace the authors list in this event in order to be able
+        to replace it with arbitrary HTML content (which might otherwise
+        end up in styled HTML in a code block).
+
+        Args:
+            html: the processed HTML of the page
+            page: mkdocs.nav.Page instance
+            config: global configuration object
+            site_navigation: global navigation object
+
+        Returns:
+            str: HTML text of page as string
+        """
+        list_pattern = re.compile(
+            r"\{\{\s*git_authors_list\s*\}\}",
+            flags=re.IGNORECASE
+        )
+        if list_pattern.search(html):
+            html = list_pattern.sub(
+                self.repo().authors_summary(),
+                html
+            )
+        return html
 
     def on_page_markdown(self, markdown, page, config, files):
         """
@@ -32,20 +98,19 @@ def on_page_markdown(self, markdown, page, config, files):
             str: Markdown source text of page as string
         """
 
-        pattern = r"\{\{\s*git_authors_summary\s*\}\}"
+        summary_pattern = re.compile(
+            r"\{\{\s*git_authors_summary\s*\}\}",
+            flags=re.IGNORECASE
+        )
 
-        if not re.search(pattern, markdown, flags=re.IGNORECASE):
-           return markdown
+        if not summary_pattern.search(markdown):
+            return markdown
 
-        authors = self.util.get_authors(
-            path = page.file.abs_src_path
+        page_obj = self.repo().page(page.file.abs_src_path)
+        return summary_pattern.sub(
+            page_obj.authors_summary(),
+            markdown
         )
-        authors_summary = self.util.summarize(authors, self.config)
-
-        return re.sub(pattern,
-                      authors_summary,
-                      markdown,
-                      flags=re.IGNORECASE)
 
     def on_page_context(self, context, page, **kwargs):
         """
@@ -66,13 +131,32 @@ def on_page_context(self, context, page, **kwargs):
             dict: template context variables
         """
 
-
-        authors = self.util.get_authors(
-            path = page.file.abs_src_path
-        )
-        authors_summary = self.util.summarize(authors, self.config)
-
-        context['git_authors'] = authors
-        context['git_authors_summary'] = authors_summary
-
-        return context
+        path = page.file.abs_src_path
+        page_obj = self.repo().page(path)
+        authors = page_obj.authors()
+
+        # NOTE: last_datetime is currently given as a
+        # string in the format
+        # '2020-02-24 17:49:14 +0100'
+        # omitting the 'str' argument would result in a
+        # datetime.datetime object with tzinfo instead.
+        # Should this be formatted differently?
+        context['git_authors'] = [
+            {
+                'name' : author.name(),
+                'email' : author.email(),
+                'last_datetime' : author.datetime(path, str),
+                'lines' : author.lines(path),
+                'contribution' : author.contribution(path, str)
+            }
+            for author in authors
+        ]
+        context['git_authors_summary'] = page_obj.authors_summary()
+
+        return context
+
+    def repo(self):
+        """
+        Reference to the Repo object of the current project.
+        """
+        return self._repo