added more doc comments; extracted convert_path function from command entries

html_to_django/__init__.py

@@ -0,0 +1,10 @@
+"""
+This package provides tools for converting special attributes in an HTML file to Django template tags.
+It includes functions for converting individual files, as well as entire directories of files.
+The conversion process involves parsing the HTML files, identifying special attributes,
+and replacing them with Django template tags.
+
+The package also includes a command line interface, which allows users to specify a file or directory to convert.
+The command line interface supports an optional flag for overwriting the original HTML files
+instead of creating new ones.
+"""

html_to_django/converter.py

@@ -8,6 +8,23 @@ from .formatters import formatters
 
 
 def get_required_libraries(soup: bs4.BeautifulSoup) -> set[str]:
+    """
+    Extracts the required libraries from a BeautifulSoup object.
+
+    The function searches for all elements with the attribute "dj-libs". For each found element, it adds the values of
+    the "dj-libs" attribute to a set. The values are expected to be library names separated by semicolons (;).
+    Then it removes the "dj-libs" attribute from the element.
+
+    Args:
+        soup (BeautifulSoup): A BeautifulSoup object representing the HTML to extract the libraries from.
+
+    Returns:
+        set[str]: A set of strings representing the names of the required libraries.
+
+    Example:
+        If the input is <div dj-libs="lib1;lib2">Content</div><div dj-libs="lib3"></div>,
+        the function returns {'lib1', 'lib2', 'lib3'}.
+    """
     libs = set()
     for element in soup.find_all(attrs={"dj-libs": True}):
         libs |= set(element.get("dj-libs").split(";"))
@@ -16,6 +33,20 @@ def get_required_libraries(soup: bs4.BeautifulSoup) -> set[str]:
 
 
 def convert_file(path: str, overwrite: bool = False) -> None:
+    """
+    Converts the special attributes in an HTML file to Django template tags.
+
+    The function reads the HTML file, parses it into a BeautifulSoup object, and applies a series of formatters to it.
+    The formatters modify the BeautifulSoup object in place, adding Django template tags based on special attributes
+    in the HTML. The function also extracts the required libraries from the BeautifulSoup object and writes them at the
+    top of the output file.
+    The output file is either the original file (if overwrite is True) or a new file with the same name but an
+    additional ".n" before the ".html" extension (if overwrite is False).
+
+    Args:
+        path (str): The path to the HTML file to be converted.
+        overwrite (bool, optional): Whether to overwrite the original file. Defaults to False.
+    """
     with open(path, "r") as file:
         soup = bs4.BeautifulSoup(file, "html.parser")
 
@@ -31,18 +62,25 @@ def convert_file(path: str, overwrite: bool = False) -> None:
     with open(out_path, "w") as file:
         for lib in required_libraries:
             file.write(f"{{% load {lib} %}}\n")
-        file.write(soup
-                   .prettify(formatter=bs4.formatter.HTMLFormatter(indent=4))
-                   .replace("&quot;", '"'))  # Could this cause any issues? (maybe in attributes)
+        file.write(soup.prettify(formatter=bs4.formatter.HTMLFormatter(indent=4)))
 
 
 def convert_dir(path: str, overwrite: bool = False) -> None:
+    """
+    Converts the special attributes in all HTML files in a directory to Django template tags.
+
+    The function traverses the directory recursively and applies the `convert_file` function to each HTML file it finds.
+
+    Args:
+        path (str): The path to the directory containing the HTML files to be converted.
+        overwrite (bool, optional): Whether to overwrite the original files. Defaults to False.
+    """
     for filepath in glob(f"{path}/**/*.html", recursive=True):
         convert_file(filepath, overwrite)
 
 
 def parse_args(name: Literal["html_to_django", "html_to_django_r"]) -> Namespace:
-    description = "Converts HTML files with special attributes to Django templates."
+    description = "Converts special attributes in HTML files to Django template tags."
     if name == "html_to_django_r":
         description = ("Info: This command is identical to html_to_django, but will always replace the input file(s)!"
                        f"\n\n{description}")
@@ -62,23 +100,61 @@ def parse_args(name: Literal["html_to_django", "html_to_django_r"]) -> Namespace
     return parser.parse_args()
 
 
-def command_entry() -> None:
-    args = parse_args("html_to_django")
-    path = os.path.abspath(args.path)
-    if os.path.isdir(path):
-        convert_dir(path, args.replace)
-    elif os.path.isfile(path):
-        convert_file(path, args.replace)
+def convert_path(path: str, overwrite: bool) -> None:
+    """
+    Converts the special attributes in the HTML files at the given path to Django template tags.
+
+    The function determines whether the provided path is a directory or a file.
+    If it's a file, it applies the `convert_file` function to convert the file.
+    If it's a directory, it applies the `convert_dir` function to convert all HTML files in the directory.
+    If the provided path does not exist, the function exits the program with an error message.
+
+    Args:
+        path (str): The path to a file or a directory of files to be converted. If a directory is passed, all HTML files
+                    in it (recursively) will be converted.
+        overwrite (bool): A flag indicating whether to replace the input files. If this flag is set, the original HTML
+                          files are overwritten with the converted Django templates. If this flag is not set, the
+                          converted Django templates are written to new files, and the original HTML files are left
+                          unchanged.
+    """
+    absolute_path = os.path.abspath(path)
+    if os.path.isdir(absolute_path):
+        convert_dir(absolute_path, overwrite)
+    elif os.path.isfile(absolute_path):
+        convert_file(absolute_path, overwrite)
     else:
-        sys.exit(f'The path "{path}" does not exist.')
+        sys.exit(f'The path "{absolute_path}" does not exist.')
+
+
+def command_entry() -> None:
+    """
+    Entry point for the command line interface of the html_to_django tool.
+
+    The function parses the command line arguments and calls `convert_path` with the parsed arguments.
+
+    The command line arguments are:
+
+    path: The path to a file or a directory of files to be converted. If a directory is passed, all HTML files in it
+    (recursively) will be converted.
+
+    replace (optional): A flag indicating whether to replace the input files. If this flag is set, the original HTML
+    files are overwritten with the converted Django templates. If this flag is not set, the converted Django templates
+    are written to new files, and the original HTML files are left unchanged.
+    """
+    args = parse_args("html_to_django")
+    convert_path(args.path, args.replace)
 
 
 def command_entry_r() -> None:
+    """
+    Entry point for the command line interface of the html_to_django_r tool.
+
+    This function is identical to `command_entry`, but it always overwrites the original HTML files.
+
+    The command line argument is:
+
+    path: The path to a file or a directory of files to be converted. If a directory is passed, all HTML files in it
+    (recursively) will be converted.
+    """
     args = parse_args("html_to_django_r")
-    path = os.path.abspath(args.path)
-    if os.path.isdir(path):
-        convert_dir(path, True)
-    elif os.path.isfile(path):
-        convert_file(path, True)
-    else:
-        sys.exit(f'The path "{path}" does not exist.')
+    convert_path(args.path, True)

html_to_django/formatters/__init__.py

@@ -1,6 +1,4 @@
 """
-formatters
-
 This package contains modules that define various formatters for modifying a BeautifulSoup object in place.
 
 Each formatter module contains a `format` function that performs a specific modification on the BeautifulSoup object.

html_to_django/formatters/attr_formatter.py

@@ -1,6 +1,4 @@
 """
-attr_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-attr".
 The value of "dj-attr" is expected to be a string with pairs of attributes and values separated by semicolons (;),

html_to_django/formatters/block_formatter.py

@@ -1,6 +1,4 @@
 """
-block_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-block". The value of "dj-block" is expected to be a
 string representing the name of a Django block. For each found element, it inserts Django block tags before and after

html_to_django/formatters/command_formatter.py

@@ -1,6 +1,4 @@
 """
-command_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-command". The value of "dj-command" is expected to be a
 string representing a Django template command. For each found element, it replaces the element's content with the Django

html_to_django/formatters/for_formatter.py

@@ -1,6 +1,4 @@
 """
-for_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-for". The value of "dj-for" is expected to be a
 string representing a Django template for loop. For each found element, it inserts a Django template for loop

html_to_django/formatters/for_wrap_formatter.py

@@ -1,6 +1,4 @@
 """
-for_wrap_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-for-wrap". The value of "dj-for-wrap" is expected to be a
 string representing a Django template for loop. For each found element, it inserts a Django template for loop

html_to_django/formatters/if_formatter.py

@@ -1,6 +1,4 @@
 """
-if_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-if". The value of "dj-if" is expected to be a
 string representing a Django template if condition. For each found element, it inserts a Django template if tag

html_to_django/formatters/include_formatter.py

@@ -1,6 +1,4 @@
 """
-include_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-include". The value of "dj-include" is expected to be a
 string representing a Django template include command. For each found element, it replaces the element's content with

html_to_django/formatters/remove_default_formatter.py

@@ -1,6 +1,4 @@
 """
-remove_default_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for the "html" element with the attribute "dj-remove-default". If such an element is found,
 the function removes the Doctype, "head" element, and "script" element within the "body" element from the BeautifulSoup

html_to_django/formatters/static_formatter.py

@@ -1,6 +1,4 @@
 """
-static_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 The function searches for all elements with the attribute "dj-static". The value of "dj-static" is expected to be a
 string representing a tag and a static file path separated by a semicolon. For each found element, it replaces the value

html_to_django/formatters/style_formatter.py

@@ -1,6 +1,4 @@
 """
-style_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place. It also contains two helper
 functions, `parse_style` and `style_to_string`.
 

html_to_django/formatters/style_raw_formatter.py

@@ -1,6 +1,4 @@
 """
-style_raw_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 
 The `format` function searches for all elements with the attribute "dj-style-raw". For each found element, it parses the

html_to_django/formatters/unwrap_formatter.py

@@ -1,6 +1,4 @@
 """
-unwrap_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 
 The `format` function searches for all elements with the attribute "dj-unwrap". For each found element, it removes the

html_to_django/formatters/var_formatter.py

@@ -1,6 +1,4 @@
 """
-var_formatter.py
-
 This module contains a function `format` that modifies a BeautifulSoup object in place.
 
 The `format` function searches for all elements with the attribute "dj-var". For each found element, it replaces the