diff --git a/html_to_django/__init__.py b/html_to_django/__init__.py
index e69de29..631a883 100644
--- a/html_to_django/__init__.py
+++ b/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.
+"""
diff --git a/html_to_django/converter.py b/html_to_django/converter.py
index fe97eea..0d06237 100644
--- a/html_to_django/converter.py
+++ b/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
Content
,
+ 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(""", '"')) # 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)
diff --git a/html_to_django/formatters/__init__.py b/html_to_django/formatters/__init__.py
index 1250135..e9f926e 100644
--- a/html_to_django/formatters/__init__.py
+++ b/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.
diff --git a/html_to_django/formatters/attr_formatter.py b/html_to_django/formatters/attr_formatter.py
index a4025c9..154a84f 100644
--- a/html_to_django/formatters/attr_formatter.py
+++ b/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 (;),
diff --git a/html_to_django/formatters/block_formatter.py b/html_to_django/formatters/block_formatter.py
index 1526c10..c6c8359 100644
--- a/html_to_django/formatters/block_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/command_formatter.py b/html_to_django/formatters/command_formatter.py
index b8f97d4..f8f1c73 100644
--- a/html_to_django/formatters/command_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/for_formatter.py b/html_to_django/formatters/for_formatter.py
index 6a039de..c167eb3 100644
--- a/html_to_django/formatters/for_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/for_wrap_formatter.py b/html_to_django/formatters/for_wrap_formatter.py
index 3b1a29a..0ca87ef 100644
--- a/html_to_django/formatters/for_wrap_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/if_formatter.py b/html_to_django/formatters/if_formatter.py
index 29d526f..d905a2b 100644
--- a/html_to_django/formatters/if_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/include_formatter.py b/html_to_django/formatters/include_formatter.py
index 4971a26..5d98ac9 100644
--- a/html_to_django/formatters/include_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/remove_default_formatter.py b/html_to_django/formatters/remove_default_formatter.py
index 6a26964..4f54715 100644
--- a/html_to_django/formatters/remove_default_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/static_formatter.py b/html_to_django/formatters/static_formatter.py
index d903d6c..31f52bf 100644
--- a/html_to_django/formatters/static_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/style_formatter.py b/html_to_django/formatters/style_formatter.py
index b0b1a4c..b2bee47 100644
--- a/html_to_django/formatters/style_formatter.py
+++ b/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`.
diff --git a/html_to_django/formatters/style_raw_formatter.py b/html_to_django/formatters/style_raw_formatter.py
index 1483adc..909a523 100644
--- a/html_to_django/formatters/style_raw_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/unwrap_formatter.py b/html_to_django/formatters/unwrap_formatter.py
index 035f6cb..77ffd31 100644
--- a/html_to_django/formatters/unwrap_formatter.py
+++ b/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
diff --git a/html_to_django/formatters/var_formatter.py b/html_to_django/formatters/var_formatter.py
index 84c131d..2c7ddd0 100644
--- a/html_to_django/formatters/var_formatter.py
+++ b/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