webwidgets 0.1.0__py3-none-any.whl

webwidgets/__init__.py

@@ -0,0 +1,15 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+__version__ = "0.1.0"  # Dynamically set by build backend
+
+from . import compilation

webwidgets/compilation/__init__.py

@@ -0,0 +1,13 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from . import html

webwidgets/compilation/html/__init__.py

@@ -0,0 +1,13 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from .html_node import HTMLNode, no_start_tag, no_end_tag, RawText

webwidgets/compilation/html/html_node.py

@@ -0,0 +1,210 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+import itertools
+from typing import Any, Dict, List, Union
+from webwidgets.utility.sanitizing import sanitize_html_text
+
+
+class HTMLNode:
+    """Represents an HTML node (for example, a div or a span).
+    """
+
+    one_line: bool = False
+
+    def __init__(self, children: List['HTMLNode'] = [], attributes: Dict[str, str] = {}):
+        """Creates an HTMLNode with optional children and attributes.
+
+        :param children: List of child HTML nodes. Defaults to an empty list.
+        :param attributes: Dictionary of attributes for the node. Defaults to an empty dictionary.
+        """
+        self.children = children
+        self.attributes = attributes
+
+    def _get_tag_name(self) -> str:
+        """Returns the tag name of the HTML node.
+
+        The tag name of a node object is the name of its class in lowercase.
+
+        :return: The tag name of the HTML node.
+        :rtype: str
+        """
+        return self.__class__.__name__.lower()
+
+    def _render_attributes(self) -> str:
+        """Renders the attributes of the HTML node into a string that can be added to the start tag.
+
+        :return: A string containing all attribute key-value pairs separated by spaces.
+        :rtype: str
+        """
+        return ' '.join(
+            f'{key}="{value}"' for key, value in self.attributes.items()
+        )
+
+    def add(self, child: 'HTMLNode') -> None:
+        """
+        Adds a child to the HTML node.
+
+        :param child: The child to be added.
+        """
+        self.children.append(child)
+
+    @property
+    def start_tag(self) -> str:
+        """Returns the opening tag of the HTML node, including any attributes.
+
+        :return: A string containing the opening tag of the element with its attributes.
+        :rtype: str
+        """
+        # Rendering attributes
+        attributes = self._render_attributes()
+        maybe_space = ' ' if attributes else ''
+
+        # Building start tag
+        return f"<{self._get_tag_name()}{maybe_space}{attributes}>"
+
+    @property
+    def end_tag(self) -> str:
+        """Returns the closing tag of the HTML node.
+
+        :return: A string containing the closing tag of the element.
+        :rtype: str
+        """
+        return f"</{self._get_tag_name()}>"
+
+    def to_html(self, collapse_empty: bool = True,
+                indent_size: int = 4, indent_level: int = 0,
+                force_one_line: bool = False, return_lines: bool = False,
+                **kwargs: Any) -> Union[str, List[str]]:
+        """Converts the HTML node into HTML code.
+
+        :param collapse_empty: If True, collapses empty elements into a single line.
+            Defaults to True.
+        :type collapse_empty: bool
+        :param indent_size: The number of spaces to use for each indentation level.
+        :type indent_size: int
+        :param indent_level: The current level of indentation in the HTML output.
+        :type indent_level: int
+        :param force_one_line: If True, forces all child elements to be rendered on a single line without additional
+            indentation. Defaults to False.
+        :type force_one_line: bool
+        :param return_lines: Whether to return the lines of HTML code individually. Defaults to False.
+        :type return_lines: bool
+        :param **kwargs: Additional keyword arguments to pass down to child elements.
+        :type **kwargs: Any
+        :return: A string containing the HTML representation of the element if
+            `return_lines` is `False` (default), or the list of individual lines
+            from that HTML code if `return_lines` is `True`.
+        :rtype: str or List[str]
+        """
+        # Opening the element
+        indentation = "" if force_one_line else ' ' * indent_size * indent_level
+        html_lines = [indentation + self.start_tag]
+
+        # If content must be in one line
+        if self.one_line or force_one_line or (collapse_empty
+                                               and not self.children):
+            html_lines += list(itertools.chain.from_iterable(
+                [c.to_html(collapse_empty=collapse_empty,
+                           indent_level=0, force_one_line=True, return_lines=True,
+                           **kwargs)
+                 for c in self.children]))
+            html_lines += [self.end_tag]
+            html_lines = [''.join(html_lines)]  # Flattening the line
+
+        # If content spans multi-line
+        else:
+            html_lines += list(itertools.chain.from_iterable(
+                [c.to_html(collapse_empty=collapse_empty,
+                           indent_size=indent_size,
+                           indent_level=indent_level + 1,
+                           return_lines=True,
+                           **kwargs)
+                 for c in self.children]))
+            html_lines += [indentation + self.end_tag]
+            html_lines = [l for l in html_lines if any(
+                c != ' ' for c in l)]  # Trimming empty lines
+
+        # If return_lines is True, return a list of lines
+        if return_lines:
+            return html_lines
+
+        # Otherwise, return a single string
+        return '\n'.join(html_lines)
+
+
+def no_start_tag(cls):
+    """Decorator to remove the start tag from an HTMLNode subclass.
+
+    :param cls: A subclass of HTMLNode whose start tag should be removed.
+    :return: The given class with an empty start tag.
+    """
+    cls.start_tag = property(
+        lambda _: '', doc="This element does not have a start tag")
+    return cls
+
+
+def no_end_tag(cls):
+    """Decorator to remove the end tag from an HTMLNode subclass.
+
+    :param cls: A subclass of HTMLNode whose end tag should be removed.
+    :return: The given class with an empty end tag.
+    """
+    cls.end_tag = property(
+        lambda _: '', doc="This element does not have an end tag")
+    return cls
+
+
+@no_start_tag
+@no_end_tag
+class RawText(HTMLNode):
+    """A raw text node that contains text without any HTML tags."""
+
+    one_line = True
+
+    def __init__(self, text: str):
+        """Creates a raw text node.
+
+        :param text: The text content of the node. It will be sanitized in
+            :py:meth:`RawText.to_html` before being written into HTML code.
+        :type text: str
+        """
+        super().__init__()
+        self.text = text
+
+    def to_html(self, indent_size: int = 4, indent_level: int = 0,
+                return_lines: bool = False, replace_all_entities: bool = False,
+                **kwargs: Any) -> Union[str, List[str]]:
+        """Converts the raw text node to HTML.
+
+        The text is sanitized by the :py:func:`sanitize_html_text` function before
+        being written into HTML code.
+
+        :param indent_size: See :py:meth:`HTMLNode.to_html`.
+        :type indent_size: int
+        :param indent_level: See :py:meth:`HTMLNode.to_html`.
+        :type indent_level: int
+        :param return_lines: See :py:meth:`HTMLNode.to_html`.
+        :type return_lines: bool
+        :param replace_all_entities: See :py:func:`sanitize_html_text`.
+        :type replace_all_entities: bool
+        :param kwargs: Other keyword arguments. These are ignored.
+        :type kwargs: Any
+        :return: See :py:meth:`HTMLNode.to_html`.
+        :rtype: str or List[str]
+        """
+        sanitized = sanitize_html_text(
+            self.text, replace_all_entities=replace_all_entities)
+        line = ' ' * indent_size * indent_level + sanitized
+        if return_lines:
+            return [line]
+        return line

webwidgets/utility/__init__.py

@@ -0,0 +1,13 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from .sanitizing import *

webwidgets/utility/sanitizing.py

@@ -0,0 +1,132 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from html.entities import html5 as HTML_ENTITIES
+import re
+from typing import Tuple
+
+
+# Maps characters to their corresponding character references. If a character can be
+# represented by multiple entities, the preferred one is placed first in the tuple.
+# Preference is given to the shortest one with a semicolon, in lowercase if possible
+# (e.g. "&amp;").
+CHAR_TO_HTML_ENTITIES = {v: sorted([
+    k for k in HTML_ENTITIES if HTML_ENTITIES[k] == v
+], key=len) for v in HTML_ENTITIES.values()}
+for _, entities in CHAR_TO_HTML_ENTITIES.items():
+    e = next((e for e in entities if ';' in e), entities[0])
+    i = entities.index(e.lower() if e.lower() in entities else e)
+    entities[i], entities[0] = entities[0], entities[i]
+CHAR_TO_HTML_ENTITIES = {k: tuple(v)
+                         for k, v in CHAR_TO_HTML_ENTITIES.items()}
+
+
+# Regular expression mathing all isolated '&' characters that are not part of an
+# HTML entity.
+_REGEX_AMP = re.compile(f"&(?!({'|'.join(HTML_ENTITIES.keys())}))")
+
+
+# Regular expression matching all isolated ';' characters that are not part of an
+# HTML entity. The expression essentially concatenates one lookbehind per entity.
+_REGEXP_SEMI = re.compile(
+    ''.join(f"(?<!&{e.replace(';', '')})"
+            for e in HTML_ENTITIES if ';' in e) + ';')
+
+
+# Entities that are always replaced during sanitization. These are: <, >, /,
+# according to rule 13.1.2.6 of the HTML5 specification, as well as single quotes
+# ', double quotes ", and new line characters '\n'.
+# Source: https://html.spec.whatwg.org/multipage/syntax.html#cdata-rcdata-restrictions
+_ALWAYS_SANITIZED = ("\u003C", "\u003E", "\u002F", "'", "\"", "\n")
+
+
+# Entities other than new line characters '\n' (which require special treatment)
+# that are always replaced during sanitization.
+_ALWAYS_SANITIZED_BUT_NEW_LINES = tuple(
+    e for e in _ALWAYS_SANITIZED if e != '\n')
+
+
+# Entities other than the ampersand and semicolon (which require special treatment
+# because they are part of other entities) that are replaced by default during
+# sanitization but can also be skipped for speed. This set of entities consists of
+# all remaining entities but the ampersand and semicolon.
+_OPTIONALLY_SANITIZED_BUT_AMP_SEMI = tuple(
+    set(CHAR_TO_HTML_ENTITIES.keys()) - set(_ALWAYS_SANITIZED) - set({'&', ';'}))
+
+
+def replace_html_entities(text: str, characters: Tuple[str]) -> str:
+    """Replaces characters with their corresponding HTML entities in the given text.
+
+    If a character can be represented by multiple entities, preference is given to
+    the shortest one that contains a semicolon, in lowercase if possible.
+
+    :param text: The input text containing HTML entities.
+    :type text: str
+    :param characters: The characters to be replaced by their HTML entity. Usually
+        each item in the tuple is a single character, but some entities span
+        multiple characters.
+    :type characters: Tuple[str]
+    :return: The text with HTML entities replaced.
+    :rtype: str
+    """
+    for c in characters:
+        entity = CHAR_TO_HTML_ENTITIES[c][0]  # Preferred is first
+        text = text.replace(c, '&' + entity)
+    return text
+
+
+def sanitize_html_text(text: str, replace_all_entities: bool = False) -> str:
+    """Sanitizes raw HTML text by replacing certain characters with HTML-friendly equivalents.
+
+    Sanitization affects the following characters:
+    - `<`, `/`, and `>`, replaced with their corresponding HTML entities `lt;`,
+        `gt;`, and `sol;` according to rule 13.1.2.6 of the HTML5 specification
+        (see source:
+        https://html.spec.whatwg.org/multipage/syntax.html#cdata-rcdata-restrictions)
+    - single quotes `'` and double quotes `"`, replaced with their corresponding
+        HTML entities `apos;` and `quot;`
+    - new line characters '\\n', replaced with `br` tags
+    - if `replace_all_entities` is True, every character that can be represented by
+        an HTML entity is replaced with that entity. If a character can be
+        represented by multiple entities, preference is given to the shortest one
+        that contains a semicolon, in lowercase if possible.
+
+    See https://html.spec.whatwg.org/multipage/named-characters.html for a list of
+    all supported entities.
+
+    :param text: The raw HTML text that needs sanitization.
+    :type text: str
+    :param replace_all_entities: Whether to replace every character that can be
+        represented by an HTML entity. Use False to skip non-mandatory characters
+        and increase speed. Default is False.
+    :type replace_all_entities: bool
+    :return: The sanitized HTML text.
+    :rtype: str
+    """
+    # We start with all optional HTML entities, which enables us to replace all '&'
+    # and ';' before subsequently introducing more of them.
+    if replace_all_entities:
+
+        # Replacing '&' ONLY when not part of an HTML entity itself
+        text = _REGEX_AMP.sub('&amp;', text)
+
+        # Replacing ';' ONLY when not part of an HTML entity itself
+        text = _REGEXP_SEMI.sub('&semi;', text)
+
+        # Replacing the remaining HTML entities
+        text = replace_html_entities(text, _OPTIONALLY_SANITIZED_BUT_AMP_SEMI)
+
+    # Then we replace all mandatory HTML entities
+    text = replace_html_entities(text, _ALWAYS_SANITIZED_BUT_NEW_LINES)
+    text = text.replace('\n', '<br>')  # Has to be last because of < and >
+
+    return text

webwidgets-0.1.0.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: webwidgets
+Version: 0.1.0
+Summary: A Python package for designing web UIs.
+Project-URL: Source code, https://github.com/mlaasri/WebWidgets
+Author: mlaasri
+License-File: LICENSE
+Keywords: design,webui
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# WebWidgets
+
+![CI Status](https://img.shields.io/github/actions/workflow/status/mlaasri/WebWidgets/ci-full.yml?branch=main)
+
+A Python package for creating web UIs

webwidgets-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+webwidgets/__init__.py,sha256=V5LcquUtoHyCfL072Oo3HNH73msF9lKd4Vx5odghyZk,481
+webwidgets/compilation/__init__.py,sha256=rebNuvAfuSVcRiuMOezktEod6C7qKl9tp__ddV4PNMg,415
+webwidgets/compilation/html/__init__.py,sha256=t7xIAup9slzxfyp-spbXFM8YxPBJF0JJyaAmMe5NmXI,463
+webwidgets/compilation/html/html_node.py,sha256=R4SsjvmbiM4WvcVuwhyXLwxYqdk9MoqVnr4idqFpZ0s,7846
+webwidgets/utility/__init__.py,sha256=6lYOxZIb_wcNGpu55FjPN9fTben37x8I2XU6HOPmADo,422
+webwidgets/utility/sanitizing.py,sha256=L72-E6er9p5e3nLupJJqcMMB62O_4lYzaDyMEyhBjE4,5768
+webwidgets-0.1.0.dist-info/METADATA,sha256=NgmpZVNES4wgiMZSIWqE1CKDtPy3YRrnlIe7DV0dcH0,550
+webwidgets-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+webwidgets-0.1.0.dist-info/licenses/LICENSE,sha256=LISw1mw5eK6i8adFSlx6zltZxrJFwurngVdZAEU8g_I,1064
+webwidgets-0.1.0.dist-info/RECORD,,

webwidgets-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

webwidgets-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mlaasri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.