diff --git a/html_to_django/formatters/__init__.py b/html_to_django/formatters/__init__.py index 2c991ed..1250135 100644 --- a/html_to_django/formatters/__init__.py +++ b/html_to_django/formatters/__init__.py @@ -1,3 +1,12 @@ +""" +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. + +The `formatters` list in this package contains all the formatter modules for easy access and usage. +""" from . import (for_formatter, if_formatter, var_formatter, block_formatter, static_formatter, attr_formatter, for_wrap_formatter, unwrap_formatter, include_formatter, remove_default_formatter, command_formatter, style_formatter, style_raw_formatter) diff --git a/html_to_django/formatters/command_formatter.py b/html_to_django/formatters/command_formatter.py index 3ce8193..b8f97d4 100644 --- a/html_to_django/formatters/command_formatter.py +++ b/html_to_django/formatters/command_formatter.py @@ -1,3 +1,16 @@ +""" +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 +template command, using the value of "dj-command" as the command. Then it removes the element's original tag, leaving +only the Django template command. + +Example: + If an element is
, + after processing, it becomes {% url 'index' %}. +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/for_formatter.py b/html_to_django/formatters/for_formatter.py index b7bc490..6a039de 100644 --- a/html_to_django/formatters/for_formatter.py +++ b/html_to_django/formatters/for_formatter.py @@ -1,3 +1,16 @@ +""" +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 +before the element and an endfor tag after the element, using the value of "dj-for" as the loop. Then it removes +the element's original tag, leaving only the Django template for loop. + +Example: + If an element is
, + after processing, it becomes {% for item in list %}{% endfor %}. +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/for_wrap_formatter.py b/html_to_django/formatters/for_wrap_formatter.py index 37c9b28..3b1a29a 100644 --- a/html_to_django/formatters/for_wrap_formatter.py +++ b/html_to_django/formatters/for_wrap_formatter.py @@ -1,3 +1,16 @@ +""" +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 +before the element and an endfor tag after the element, using the value of "dj-for-wrap" as the loop. Then it removes +the "dj-for-wrap" attribute from the element, leaving the element wrapped in the Django template for loop. + +Example: + If an element is
Content
, + after processing, it becomes {% for item in list %}
Content
{% endfor %}. +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/if_formatter.py b/html_to_django/formatters/if_formatter.py index 5d1c7d9..29d526f 100644 --- a/html_to_django/formatters/if_formatter.py +++ b/html_to_django/formatters/if_formatter.py @@ -1,3 +1,17 @@ +""" +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 +before the element. If there are subsequent siblings with "dj-elif" or "dj-else" attributes, it also processes them +appropriately to form a complete Django template if-elif-else structure. Then it removes the original tags, leaving +only the Django template if-elif-else structure. + +Example: + If the elements are
Test
Test2
Test3
, + after processing, they become {% if condition1 %}Test{% elif condition2 %}Test2{% else %}Test3{% endif %}. +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/include_formatter.py b/html_to_django/formatters/include_formatter.py index f8cb988..4971a26 100644 --- a/html_to_django/formatters/include_formatter.py +++ b/html_to_django/formatters/include_formatter.py @@ -1,3 +1,16 @@ +""" +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 +the Django template include command, using the value of "dj-include" as the command. +Then it removes the "dj-include" attribute from the element. + +Example: + If an element is
, + after processing, it becomes {% include "template_name.html" %}. +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/remove_default_formatter.py b/html_to_django/formatters/remove_default_formatter.py index f69a792..6a26964 100644 --- a/html_to_django/formatters/remove_default_formatter.py +++ b/html_to_django/formatters/remove_default_formatter.py @@ -1,3 +1,15 @@ +""" +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 +object. It also unwraps the "body" and "html" elements, leaving only the remaining content of the "body" element. + +Example: + If the html is Content, + after processing, it becomes Content. +""" from bs4 import BeautifulSoup, Doctype, Tag diff --git a/html_to_django/formatters/static_formatter.py b/html_to_django/formatters/static_formatter.py index 0f2c805..d903d6c 100644 --- a/html_to_django/formatters/static_formatter.py +++ b/html_to_django/formatters/static_formatter.py @@ -1,3 +1,16 @@ +""" +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 +of the specified tag with a Django template static command, using the specified static file path. +Then it removes the "dj-static" attribute from the element. + +Example: + If an element is , + after processing, it becomes . +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/style_formatter.py b/html_to_django/formatters/style_formatter.py index 9f04db6..b0b1a4c 100644 --- a/html_to_django/formatters/style_formatter.py +++ b/html_to_django/formatters/style_formatter.py @@ -1,7 +1,48 @@ +""" +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`. + +The `parse_style` function takes a string of CSS styles and parses it into a dictionary where keys are +CSS property names and values are the corresponding CSS values. + +The `style_to_string` function takes a dictionary of CSS styles and converts it into a string representation. + +The `format` function searches for all elements with the attribute "dj-style". For each found element, it parses the +existing style attributes (if any), merges them with the styles specified in "dj-style", and replaces the +style attribute with the merged styles. The values of the "dj-style" attribute are expected to be strings with pairs of +CSS properties, values, and value types separated by semicolons (;), and each triplet separated by tildes (~). +The value is inserted into the style attribute in Django template variable format (i.e., "{{ value }}"). +If a value type is specified, it is appended to the value in the style attribute. +The value type can be omitted if not needed. In that case make sure to keep the semicolon at the end of the value. +Then it removes the "dj-style" attribute from the element. + +Example: + If an element is
, + after processing, it becomes
. +""" from bs4 import BeautifulSoup def parse_style(style: str) -> dict[str, str]: + """ + Parses a string of CSS styles into a dictionary. + + The function takes a string where each CSS property and its corresponding value are separated by a colon, + and each property-value pair is separated by a semicolon. + It splits the string into key-value pairs and stores them in a dictionary. + + Args: + style (str): A string of CSS styles. + + Returns: + dict[str, str]: A dictionary where keys are CSS property names and values are the corresponding CSS values. + + Example: + If the input is 'color:red;background-color:blue;', + the output will be {'color': 'red', 'background-color': 'blue'}. + """ result: dict[str, str] = {} key_buffer = "" buffer = "" @@ -21,6 +62,23 @@ def parse_style(style: str) -> dict[str, str]: def style_to_string(style: dict[str, str]) -> str: + """ + Converts a dictionary of CSS styles into a string representation. + + The function takes a dictionary where keys are CSS property names and values are the corresponding CSS values. + It joins all the items in the dictionary into a string, with each key-value pair separated by a colon and each pair + separated by a semicolon. + + Args: + style (dict[str, str]): A dictionary of CSS styles. + + Returns: + str: A string representation of the CSS styles. + + Example: + If the input is {'color': 'red', 'background-color': 'blue'}, + the output will be 'color:red;background-color:blue;'. + """ result = ";".join([f"{name}:{value}" for name, value in style.items()]) if len(style) != 0: result += ";" diff --git a/html_to_django/formatters/style_raw_formatter.py b/html_to_django/formatters/style_raw_formatter.py index fd39c73..1483adc 100644 --- a/html_to_django/formatters/style_raw_formatter.py +++ b/html_to_django/formatters/style_raw_formatter.py @@ -1,3 +1,19 @@ +""" +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 +existing style attributes (if any), merges them with the styles specified in "dj-style-raw", and replaces the +style attribute with the merged styles. The values of the "dj-style-raw" attribute are expected to be strings with pairs +of CSS properties and values separated by semicolons (;), and each pair separated by tildes (~). +Unlike the `style_formatter` module, this module does not insert the values into the style attribute in Django template +variable format. Then it removes the "dj-style-raw" attribute from the element. + +Example: + If an element is
, + after processing, it becomes
. +""" from bs4 import BeautifulSoup from .style_formatter import parse_style, style_to_string diff --git a/html_to_django/formatters/unwrap_formatter.py b/html_to_django/formatters/unwrap_formatter.py index fb91dbb..035f6cb 100644 --- a/html_to_django/formatters/unwrap_formatter.py +++ b/html_to_django/formatters/unwrap_formatter.py @@ -1,3 +1,15 @@ +""" +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 +element's tags but keeps its content. + +Example: + If an element is

Hello, world!

, + after processing, it becomes

Hello, world!

. +""" from bs4 import BeautifulSoup diff --git a/html_to_django/formatters/var_formatter.py b/html_to_django/formatters/var_formatter.py index 3b2440a..84c131d 100644 --- a/html_to_django/formatters/var_formatter.py +++ b/html_to_django/formatters/var_formatter.py @@ -1,9 +1,16 @@ """ -Find tags with a "dj-var" attribute and replace its content with the -value enclosed in {{ }}. +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 +element's content with a Django template variable that has the same name as the value of the "dj-var" attribute. +Then it removes the "dj-var" attribute from the element. + +Example: + If an element is

Hello, world!

, + after processing, it becomes

{{ greeting }}

. """ - - from bs4 import BeautifulSoup