webwidgets 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

webwidgets/__init__.py

@@ -10,6 +10,6 @@
 #
 # =======================================================================
 
-__version__ = "0.1.0"  # Dynamically set by build backend
+__version__ = "0.2.0"  # Dynamically set by build backend
 
 from . import compilation

webwidgets/compilation/__init__.py

@@ -10,4 +10,5 @@
 #
 # =======================================================================
 
+from . import css
 from . import html

webwidgets/compilation/css/__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 .css import compile_css, CompiledCSS, apply_css

webwidgets/compilation/css/css.py

@@ -0,0 +1,171 @@
+# =======================================================================
+#
+#  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 Dict, List, Union
+from webwidgets.compilation.html.html_node import HTMLNode
+from webwidgets.utility.validation import validate_css_identifier
+
+
+class CompiledCSS:
+    """A utility class to hold compiled CSS rules.
+    """
+
+    def __init__(self, trees: List[HTMLNode], rules: Dict[str, Dict[str, str]],
+                 mapping: Dict[int, List[str]]):
+        """Stores compiled CSS rules.
+
+        :param trees: The HTML trees at the origin of the compilation. These
+            are the elements that have been styled with CSS properties.
+        :type trees: List[HTMLNode]
+        :param rules: The compiled CSS rules, specified as a dictionary mapping
+            the rule's name to its corresponding CSS declarations. For example:
+            `{'r0': {'color': 'red'}}`.
+        :type rules: Dict[str, Dict[str, str]]
+        :param mapping: A dictionary mapping each node ID to a list of rules
+            that achieve the same style. Rules must be specified by their name.
+            For example: `{123: ['r0', 'r2'], 456: ['r1']}`.
+        :type mapping: Dict[int, List[str]]
+        """
+        self.trees = trees
+        self.rules = rules
+        self.mapping = mapping
+
+    def to_css(self, indent_size: int = 4) -> str:
+        """Converts the `rules` dictionary of the :py:class:`CompiledCSS`
+        object into CSS code.
+
+        Each rule name is converted to a class selector and each property name
+        is validated with :py:func:`validate_css_identifier` before being
+        converted.
+
+        :param indent_size: The number of spaces to use for indentation in the
+            CSS code. Defaults to 4.
+        :type indent_size: int
+        :return: The CSS code as a string.
+        :rtype: str
+        """
+        # Initializing code and defining indentation
+        css_code = ""
+        indentation = ' ' * indent_size
+
+        # Writing down each rule from the rules dictionary
+        for i, (name, declarations) in enumerate(self.rules.items()):
+            css_code += f".{name}" + " {\n"
+            for property_name, value in declarations.items():
+                validate_css_identifier(property_name)
+                css_code += f"{indentation}{property_name}: {value};\n"
+            css_code += "}" + ('\n\n' if i < len(self.rules) - 1 else '')
+
+        return css_code
+
+
+def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
+    """Computes optimized CSS rules from the given HTML trees.
+
+    The main purpose of this function is to reduce the number of CSS rules
+    required to achieve a particular style across one or more HTML trees. The
+    function takes a list of HTML nodes as input (not necessarily from the same
+    tree) and computes an optimized set of CSS rules that achieves the same
+    style across all nodes. The resulting :py:class:`CompiledCSS` object
+    contains the optimized rules and their mapping to each node.
+
+    For example, the following tree:
+
+    .. code-block:: python
+
+        tree = HTMLNode(
+            style={"margin": "0", "padding": "0"},
+            children=[
+                HTMLNode(style={"margin": "0", "padding": "0"}),
+                HTMLNode(style={"margin": "0", "color": "blue"}),
+            ]
+        )
+
+    can be stylistically described with only 3 CSS rules:
+
+    .. code-block:: python
+
+        >>> compiled_css = compile_css(tree)
+        >>> print(compiled_css.rules)
+        {
+            'r0': {'color': 'blue'},
+            'r1': {'margin': '0'},
+            'r2': {'padding': '0'}
+        }
+
+    :param trees: A single tree or a list of trees to optimize over. All
+        children are recursively included in the compilation.
+    :type trees: Union[HTMLNode, List[HTMLNode]]
+    :return: The :py:class:`CompiledCSS` object containing the optimized rules.
+        Every HTML node present in one or more of the input trees is included
+        in the :py:attr:`CompiledCSS.mapping` attribute, even if the node does
+        not have a style. Rules are alphabetically ordered by name in the
+        mapping.
+    :rtype: CompiledCSS
+    """
+    # Handling case of a single tree
+    if isinstance(trees, HTMLNode):
+        trees = [trees]
+
+    # For now, we just return a simple mapping where each CSS property defines
+    # its own ruleset
+    styles = {k: v for tree in trees for k, v in tree.get_styles().items()}
+    properties = set(itertools.chain.from_iterable(s.items()
+                     for s in styles.values()))
+    rules = {f"r{i}": dict([p]) for i, p in enumerate(sorted(properties))}
+    mapping = {node_id: sorted([n for n, r in rules.items() if
+                                set(r.items()).issubset(style.items())])
+               for node_id, style in styles.items()}
+    return CompiledCSS(trees, rules, mapping)
+
+
+def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
+    """Applies the CSS rules to the given tree.
+
+    Rules are added as HTML classes to each node with a style in the tree. If a
+    node does not have a `class` attribute yet, it will be created for that
+    node. Nodes that do not have any style are left untouched.
+
+    Note that this function is recursive and calls itself on each child node of
+    the tree.
+
+    :param css: The compiled CSS object containing the rules to apply and the
+        mapping to each node. It should have been created by invoking
+        :py:func:`compile_css` on the given tree, but it can be modified before
+        passing it to this function, as long as its content remains consistent.
+    :type css: CompiledCSS
+    :param tree: The tree to which the CSS rules should be applied. It will be
+        modified in place by this function. If you want to keep the original
+        tree unchanged, make a deep copy of it using its
+        :py:meth:`HTMLNode.copy` method and pass this copy instead.
+    :type tree: HTMLNode
+    """
+    # Only modifying nodes if they have a style (and therefore if the list of
+    # rules mapped to them in `css.mapping` is not empty)
+    if tree.style:
+
+        # Listing rules to add as classes. We do not add rules that are already
+        # there.
+        rules_to_add = [r for r in css.mapping[id(tree)] if r and r not in
+                        tree.attributes.get('class', '').split(' ')]
+
+        # Updating the class attribute. If it already exists and is not empty,
+        # we need to insert a space before adding the CSS classes.
+        maybe_space = ' ' if tree.attributes.get(
+            'class', None) and rules_to_add else ''
+        tree.attributes['class'] = tree.attributes.get(
+            'class', '') + maybe_space + ' '.join(rules_to_add)
+
+    # Recursively applying the CSS rules to all child nodes of the tree
+    for child in tree.children:
+        apply_css(css, child)

webwidgets/compilation/html/__init__.py

@@ -10,4 +10,5 @@
 #
 # =======================================================================
 
-from .html_node import HTMLNode, no_start_tag, no_end_tag, RawText
+from .html_node import HTMLNode, no_start_tag, no_end_tag, one_line, RawText
+from .html_tags import TextNode

webwidgets/compilation/html/html_node.py

@@ -10,9 +10,11 @@
 #
 # =======================================================================
 
+import copy
 import itertools
 from typing import Any, Dict, List, Union
 from webwidgets.utility.sanitizing import sanitize_html_text
+from webwidgets.utility.validation import validate_html_class
 
 
 class HTMLNode:
@@ -21,14 +23,20 @@ class HTMLNode:
 
     one_line: bool = False
 
-    def __init__(self, children: List['HTMLNode'] = [], attributes: Dict[str, str] = {}):
-        """Creates an HTMLNode with optional children and attributes.
+    def __init__(self, children: List['HTMLNode'] = None,
+                 attributes: Dict[str, str] = None, style: Dict[str, str] = None):
+        """Creates an HTMLNode with optional children, attributes, and style.
 
         :param children: List of child HTML nodes. Defaults to an empty list.
+        :type children: List[HTMLNode]
         :param attributes: Dictionary of attributes for the node. Defaults to an empty dictionary.
+        :type attributes: Dict[str, str]
+        :param style: Dictionary of CSS properties for the node. Defaults to an empty dictionary.
+        :type style: Dict[str, str]
         """
-        self.children = children
-        self.attributes = attributes
+        self.children = [] if children is None else children
+        self.attributes = {} if attributes is None else attributes
+        self.style = {} if style is None else style
 
     def _get_tag_name(self) -> str:
         """Returns the tag name of the HTML node.
@@ -51,21 +59,55 @@ class HTMLNode:
         )
 
     def add(self, child: 'HTMLNode') -> None:
-        """
-        Adds a child to the HTML node.
+        """Adds a child to the HTML node.
 
         :param child: The child to be added.
         """
         self.children.append(child)
 
+    def copy(self, deep: bool = False) -> 'HTMLNode':
+        """Returns a copy of the HTML node.
+
+        This method is just a convenient wrapper around Python's
+        `copy.copy()` and `copy.deepcopy()` methods.
+
+        :param deep: If True, creates a deep copy of the node and its children,
+            recursively. Otherwise, creates a shallow copy. Defaults to False.
+        :type deep: bool
+        :return: A new HTMLNode object that is a copy of the original.
+        :rtype: HTMLNode
+        """
+        if deep:
+            return copy.deepcopy(self)
+        return copy.copy(self)
+
+    def get_styles(self) -> Dict[int, Dict[str, str]]:
+        """Returns a dictionary mapping the node and all its children,
+        recursively, to their style.
+
+        Nodes are identified by their ID as obtained from Python's built-in
+        `id()` function.
+
+        :return: A dictionary mapping node IDs to styles.
+        :rtype: Dict[int, Dict[str, str]]
+        """
+        styles = {id(self): self.style}
+        for child in self.children:
+            styles.update(child.get_styles())
+        return styles
+
     @property
     def start_tag(self) -> str:
         """Returns the opening tag of the HTML node, including any attributes.
 
+        Attributes are validated with :py:meth:`HTMLNode.validate_attributes`
+        before rendering.
+
         :return: A string containing the opening tag of the element with its attributes.
         :rtype: str
         """
         # Rendering attributes
+        self.validate_attributes()
         attributes = self._render_attributes()
         maybe_space = ' ' if attributes else ''
 
@@ -87,8 +129,8 @@ class HTMLNode:
                 **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.
+        :param collapse_empty: If True, collapses elements without any children
+            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
@@ -141,6 +183,13 @@ class HTMLNode:
         # Otherwise, return a single string
         return '\n'.join(html_lines)
 
+    def validate_attributes(self) -> None:
+        """Validate the node's attributes and raises an exception with a
+        descriptive error message if any attribute is invalid.
+        """
+        if "class" in self.attributes:
+            validate_html_class(self.attributes["class"])
+
 
 def no_start_tag(cls):
     """Decorator to remove the start tag from an HTMLNode subclass.
@@ -164,13 +213,22 @@ def no_end_tag(cls):
     return cls
 
 
+def one_line(cls):
+    """Decorator to make an HTMLNode subclass a one-line element.
+
+    :param cls: A subclass of HTMLNode.
+    :return: The given class with the `one_line` attribute set to True.
+    """
+    cls.one_line = True
+    return cls
+
+
 @no_start_tag
 @no_end_tag
+@one_line
 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.
 

webwidgets/compilation/html/html_tags.py

@@ -0,0 +1,40 @@
+# =======================================================================
+#
+#  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, one_line, RawText
+from typing import Dict
+
+
+@one_line
+class TextNode(HTMLNode):
+    """A one-line HTML element that only contains raw text (like `<h1>`).
+
+    A text node renders on one line and only contains one child: a
+    :py:class:`RawText` node with the text to be rendered.
+    """
+
+    def __init__(self, text: str, attributes: Dict[str, str] = None,
+                 style: Dict[str, str] = None):
+        """Creates a new text node with the given text and attributes.
+
+        :param text: The text content of the node.
+        :type text: str
+        :param attributes: See :py:meth:`HTMLNode.__init__`. Defaults to an
+            empty dictionary.
+        :type attributes: Dict[str, str]
+        :param style: See :py:meth:`HTMLNode.__init__`. Defaults to an empty
+            dictionary.
+        :type style: Dict[str, str]
+        """
+        super().__init__(children=[
+            RawText(text)
+        ], attributes=attributes, style=style)

webwidgets/utility/__init__.py

@@ -11,3 +11,4 @@
 # =======================================================================
 
 from .sanitizing import *
+from .validation import *

webwidgets/utility/sanitizing.py

@@ -30,7 +30,7 @@ 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
+# Regular expression matching all isolated '&' characters that are not part of an
 # HTML entity.
 _REGEX_AMP = re.compile(f"&(?!({'|'.join(HTML_ENTITIES.keys())}))")
 
@@ -107,7 +107,7 @@ def sanitize_html_text(text: str, replace_all_entities: bool = False) -> str:
     :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.
+        and increase speed. Defaults to False.
     :type replace_all_entities: bool
     :return: The sanitized HTML text.
     :rtype: str

webwidgets/utility/validation.py

@@ -0,0 +1,97 @@
+# =======================================================================
+#
+#  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 typing import *
+import re
+
+
+def validate_css_identifier(identifier: str) -> None:
+    """Checks if the given identifier is a valid identifier token according to
+    the CSS syntax rules and raises an exception if not.
+
+    An identifier token is a sequence of characters that can be used as part of
+    a CSS rule, like a class name or an ID. The concept essentially corresponds
+    to that of an `ident-token` in the official CSS specification.
+
+    This function enforces the following rules:
+    - the identifier must only contain letters (`a-z`, `A-Z`), digits (`0-9`),
+      underscores (`_`), and hyphens (`-`)
+    - the identifier must start with either a letter, an underscore, or a
+      double hyphen (`--`)
+
+    Note that this function imposes stricter rules on identifier tokens than
+    the official CSS specification - more precisely, than chapter 4 of the CSS
+    Syntax Module Level 3 (see source:
+    https://www.w3.org/TR/css-syntax-3/#tokenization - note that this chapter
+    remains the same in the current draft for Level 4). For example, this
+    function does not allow escaped special characters nor identifier tokens
+    starting with a single hyphen whereas the specification does.
+
+    :param identifier: The string to be validated as an identifier token.
+    :type identifier: str
+    :raises ValueError: If the identifier is not a valid identifier token and
+        does not respect the specified rules.
+    """
+    # Check if identifier starts with anything else than a letter, an
+    # underscore, or a double hyphen
+    if not re.match(r'^[a-zA-Z_]+|--', identifier):
+        raise ValueError("CSS identifier must start with either a letter, an "
+                         "underscore, or a double hyphen (`--`), but got: "
+                         f"'{identifier}'")
+
+    # Check if identifier contains invalid characters
+    if not re.match(r'^[a-zA-Z0-9_-]+$', identifier):
+        invalid_chars = re.findall('[^a-zA-Z0-9_-]', identifier)
+        raise ValueError("Invalid character(s) in CSS idenfitier "
+                         f"'{identifier}': {', '.join(invalid_chars)}\n"
+                         "Only letters, digits, hyphens, and underscores are "
+                         "allowed.")
+
+
+def validate_html_class(class_attribute: str) -> None:
+    """Checks if the given HTML class attribute is valid and raises an
+    exception if not.
+
+    This function enforces the following rules:
+    - the class attribute cannot start nor end with a space
+    - the class attribute cannot contain double spaces
+    - each class in the attribute must be a valid CSS identifier, as validated
+      by the :py:func:`validate_css_identifier` function.
+
+    Note that this function imposes stricter rules than rule 2.3.7 of the HTML5
+    specification (see source:
+    https://html.spec.whatwg.org/#set-of-space-separated-tokens). For example,
+    it does not allow for leading nor trailing spaces whereas the specification
+    does.
+
+    :param class_attribute: The HTML class attribute to be validated.
+    :type class_attribute: str
+    :raises ValueError: If the class attribute is invalid and does not respect
+        the specified rules.
+    """
+    # Allow for empty attribute
+    if not class_attribute:
+        return
+
+    # Check if the class attribute starts or ends with a space
+    if class_attribute.startswith(' ') or class_attribute.endswith(' '):
+        raise ValueError("Class attribute cannot start nor end with a space, "
+                         f"but got: '{class_attribute}'")
+
+    # Check for double spaces in the class attribute
+    if '  ' in class_attribute:
+        raise ValueError("Class attribute cannot contain double spaces, "
+                         f"but got: '{class_attribute}'")
+
+    # Check each class individually
+    for c in class_attribute.split(' '):
+        validate_css_identifier(c)

{webwidgets-0.1.0.dist-info → webwidgets-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webwidgets
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Python package for designing web UIs.
 Project-URL: Source code, https://github.com/mlaasri/WebWidgets
 Author: mlaasri

webwidgets-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+webwidgets/__init__.py,sha256=jkCnUIqDE1LjArrZKtl1Bpm9bf-ZmLUP5JBRTh3gayA,481
+webwidgets/compilation/__init__.py,sha256=hb61nhmPTghIzuA_hun98xT5Ngv7QFAgMHD44g-9uOo,433
+webwidgets/compilation/css/__init__.py,sha256=Yzk_Bq1ey8Bf4dcKNd_priwj6_DA9CwG9wFs-BbZRGE,449
+webwidgets/compilation/css/css.py,sha256=8VjlXQtjY2fuhg49VtUi1RZF__Z7-qtj9-FAw3ZAtZA,7160
+webwidgets/compilation/html/__init__.py,sha256=NRccbCUKdhmK51MnYFO8q1sS8fWhAggRnMiGDG7lQMQ,505
+webwidgets/compilation/html/html_node.py,sha256=IEkb_zfIexU59cEk2Gf7nBo9Tm13DN_siLF7TBIGF1k,10095
+webwidgets/compilation/html/html_tags.py,sha256=U2HmhLkV6BOqTmgvIMlmMCQysQ7i2nEAVWJzZe74ucA,1388
+webwidgets/utility/__init__.py,sha256=_L0RxTAzAhjgZqg0eKEqpCJJeN_W2P9p5Clu7PETqCQ,448
+webwidgets/utility/sanitizing.py,sha256=OKJRDqk-OXYCWeK6ie3GdfQvb49wTs93kd971mg5oK0,5770
+webwidgets/utility/validation.py,sha256=bUjpiGP59GW3DPvQ1hwR5ezBMmcSd6v4xlDLwTHZv_A,4261
+webwidgets-0.2.0.dist-info/METADATA,sha256=WDQK0YqoVt7imhRbXDw3QjrG9UgCflSvbHYDiNRM1mU,550
+webwidgets-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+webwidgets-0.2.0.dist-info/licenses/LICENSE,sha256=LISw1mw5eK6i8adFSlx6zltZxrJFwurngVdZAEU8g_I,1064
+webwidgets-0.2.0.dist-info/RECORD,,

webwidgets-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-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,,