From f80d827957b84c993ac1f521f47b6518341ede23 Mon Sep 17 00:00:00 2001
From: Kumi <git@kumi.email>
Date: Wed, 19 Jun 2024 09:54:44 +0200
Subject: [PATCH] feat(markdown): enhance URL rewriting with better docstrings

Added detailed docstrings to the `RelativeURLRewriter` class and its methods
to improve code readability and maintainability. The docstrings provide
clear descriptions of the purpose, arguments, and return values for the
class and its subfunctions, aiding future developers in understanding
the URL rewriting process more easily.
---
 src/gitcloak/classes/markdown.py | 38 ++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/src/gitcloak/classes/markdown.py b/src/gitcloak/classes/markdown.py
index be8b621..cc8f059 100644
--- a/src/gitcloak/classes/markdown.py
+++ b/src/gitcloak/classes/markdown.py
@@ -1,19 +1,49 @@
 import re
 import markdown2
 
+
 class RelativeURLRewriter(markdown2.Markdown):
+    """A Markdown postprocessor that rewrites relative URLs to match the raw file URL."""
+
     def __init__(self, base_url, *args, **kwargs):
+        """Initialize the RelativeURLRewriter.
+
+        Args:
+            base_url (str): The base URL to prepend to relative URLs.
+        """
         self.base_url = base_url
         super().__init__(*args, **kwargs)
 
-    def postprocess(self, text):
-        # Rewrite relative URLs
+    def postprocess(self, text: str) -> str:
+        """Rewrite relative URLs in the Markdown text.
+
+        Args:
+            text (str): The Markdown text.
+
+        Returns:
+            str: The Markdown text with relative URLs rewritten.
+        """
+
         def replace_url(match):
+            """A subfunction to replace the URL in a found match.
+
+            Args:
+                match (re.Match): The match object.
+
+            Returns:
+                str: The replacement string, either the original URL or the rewritten URL.
+            """
+
             url = match.group(1)
-            if not (":" in url or url.startswith("/") or url.startswith("#") or url.startswith("md5-")):
+            if not (
+                ":" in url
+                or url.startswith("/")
+                or url.startswith("#")
+                or url.startswith("md5-")
+            ):
                 return f'src="{self.base_url}/{url}"'
             return match.group(0)
 
         text = re.sub(r'src="([^"]+)"', replace_url, text)
         text = re.sub(r'href="([^"]+)"', replace_url, text)
-        return text
\ No newline at end of file
+        return text