From d4f53e49d91fd2ff142d833ab9cb1a126dadf29b Mon Sep 17 00:00:00 2001 From: truePhilipp Date: Tue, 7 May 2024 19:54:26 +0200 Subject: [PATCH] added more doc comments; extracted convert_path function from command entries --- html_to_django/__init__.py | 10 ++ html_to_django/converter.py | 114 +++++++++++++++--- html_to_django/formatters/__init__.py | 2 - html_to_django/formatters/attr_formatter.py | 2 - html_to_django/formatters/block_formatter.py | 2 - .../formatters/command_formatter.py | 2 - html_to_django/formatters/for_formatter.py | 2 - .../formatters/for_wrap_formatter.py | 2 - html_to_django/formatters/if_formatter.py | 2 - .../formatters/include_formatter.py | 2 - .../formatters/remove_default_formatter.py | 2 - html_to_django/formatters/static_formatter.py | 2 - html_to_django/formatters/style_formatter.py | 2 - .../formatters/style_raw_formatter.py | 2 - html_to_django/formatters/unwrap_formatter.py | 2 - html_to_django/formatters/var_formatter.py | 2 - 16 files changed, 105 insertions(+), 47 deletions(-) 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