webwidgets 0.2.0__tar.gz → 0.2.1__tar.gz

{webwidgets-0.2.0 → webwidgets-0.2.1}/PKG-INFO

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

{webwidgets-0.2.0 → webwidgets-0.2.1}/tests/compilation/test_css.py

@@ -11,12 +11,38 @@
 # =======================================================================
 
 import pytest
+from typing import Any, Dict, List
 from webwidgets.compilation.html.html_node import HTMLNode
 from webwidgets.compilation.html.html_tags import TextNode
-from webwidgets.compilation.css.css import compile_css, CompiledCSS, apply_css
+from webwidgets.compilation.css.css import compile_css, CSSRule, CompiledCSS, \
+    apply_css, default_rule_namer
 
 
 class TestCompileCSS:
+    @staticmethod
+    def _serialize_rules(rules: List[CSSRule]) -> List[Dict[str, Any]]:
+        """Utility function to convert a list of :py:class:`CSSRule` objects
+        into a dictionary that can be used in testing.
+
+        :param rules: List of :py:class:`CSSRule` objects.
+        :type rules: List[CSSRule]
+        :return: List of the member variables of each :py:class:`CSSRule`.
+        :rtype: Dict[int, Any]
+        """
+        return [vars(rule) for rule in rules]
+
+    @staticmethod
+    def _serialize_mapping(mapping: Dict[int, List[CSSRule]]) -> Dict[int, List[str]]:
+        """Utility function to convert a :py:attr:`CompiledCSS.mapping` object
+        into a dictionary that can be used in testing.
+
+        :param mapping: :py:attr:`CompiledCSS.mapping` object.
+        :type mapping: Dict[int, List[CSSRule]]
+        :return: Dictionary mapping each node ID to the name of the rules that
+            achieve the same style.
+        """
+        return {i: [r.name for r in rules] for i, rules in mapping.items()}
+
     def test_argument_type(self):
         """Compares compilation when given a node object versus a list of
         nodes.
@@ -30,10 +56,10 @@ class TestCompileCSS:
         )
 
         # Define expected compilation results
-        expected_rules = {
-            'r0': {'a': '5'},
-            'r1': {'b': '4'}
-        }
+        expected_rules = [
+            {"name": "r0", "declarations": {"a": "5"}},
+            {"name": "r1", "declarations": {"b": "4"}}
+        ]
         expected_mapping = {
             id(tree): ['r0', 'r1'],
             id(tree.children[0]): ['r0']
@@ -45,8 +71,10 @@ class TestCompileCSS:
         # Check results of compilation
         assert compiled_css.trees == [tree]
         assert [id(t) for t in compiled_css.trees] == [id(tree)]
-        assert compiled_css.rules == expected_rules
-        assert compiled_css.mapping == expected_mapping
+        assert TestCompileCSS._serialize_rules(
+            compiled_css.rules) == expected_rules
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css.mapping) == expected_mapping
 
         # Compile tree as list of one node
         compiled_css2 = compile_css([tree])
@@ -54,8 +82,10 @@ class TestCompileCSS:
         # Check results of compilation again (should be unchanged)
         assert compiled_css2.trees == [tree]
         assert [id(t) for t in compiled_css2.trees] == [id(tree)]
-        assert compiled_css2.rules == expected_rules
-        assert compiled_css2.mapping == expected_mapping
+        assert TestCompileCSS._serialize_rules(
+            compiled_css2.rules) == expected_rules
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css2.mapping) == expected_mapping
 
     def test_basic_compilation(self):
         # Create some HTML nodes with different styles
@@ -72,17 +102,19 @@ class TestCompileCSS:
             id(node1), id(node2), id(node3)]
 
         # Check that the rules are correctly generated
-        expected_rules = {
-            'r0': {'color': 'blue'},
-            'r1': {'margin': '0'},
-            'r2': {'padding': '0'}
-        }
-        assert compiled_css.rules == expected_rules
+        expected_rules = [
+            {"name": "r0", "declarations": {"color": "blue"}},
+            {"name": "r1", "declarations": {"margin": "0"}},
+            {"name": "r2", "declarations": {"padding": "0"}}
+        ]
+        assert TestCompileCSS._serialize_rules(
+            compiled_css.rules) == expected_rules
 
         # Check that the mapping is correctly generated
         expected_mapping = {id(node1): ['r1', 'r2'], id(
             node2): ['r0', 'r1'], id(node3): ['r1', 'r2']}
-        assert compiled_css.mapping == expected_mapping
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css.mapping) == expected_mapping
 
     def test_nested_compilation_one_tree(self):
         # Create some nested HTML nodes
@@ -104,13 +136,14 @@ class TestCompileCSS:
         assert [id(t) for t in compiled_css.trees] == [id(tree)]
 
         # Check that the rules are correctly generated
-        expected_rules = {
-            'r0': {'color': 'blue'},
-            'r1': {'margin': '0'},
-            'r2': {'margin': '5'},
-            'r3': {'padding': '0'}
-        }
-        assert compiled_css.rules == expected_rules
+        expected_rules = [
+            {"name": "r0", "declarations": {"color": "blue"}},
+            {"name": "r1", "declarations": {"margin": "0"}},
+            {"name": "r2", "declarations": {"margin": "5"}},
+            {"name": "r3", "declarations": {"padding": "0"}}
+        ]
+        assert TestCompileCSS._serialize_rules(
+            compiled_css.rules) == expected_rules
 
         # Check that the mapping is correctly generated
         expected_mapping = {
@@ -120,7 +153,8 @@ class TestCompileCSS:
             id(tree.children[0].children[0]): [],
             id(tree.children[1].children[0]): []
         }
-        assert compiled_css.mapping == expected_mapping
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css.mapping) == expected_mapping
 
     def test_nested_compilation_two_trees(self):
         # Create 2 trees
@@ -146,13 +180,14 @@ class TestCompileCSS:
             id(tree1), id(tree2)]
 
         # Check that the rules are correctly generated
-        expected_rules = {
-            'r0': {'color': 'red'},
-            'r1': {'margin': '10'},
-            'r2': {'margin': '5'},
-            'r3': {'padding': '0'}
-        }
-        assert compiled_css.rules == expected_rules
+        expected_rules = [
+            {"name": "r0", "declarations": {"color": "red"}},
+            {"name": "r1", "declarations": {"margin": "10"}},
+            {"name": "r2", "declarations": {"margin": "5"}},
+            {"name": "r3", "declarations": {"padding": "0"}}
+        ]
+        assert TestCompileCSS._serialize_rules(
+            compiled_css.rules) == expected_rules
 
         # Check that the mapping is correctly generated
         expected_mapping = {
@@ -161,7 +196,8 @@ class TestCompileCSS:
             id(tree2): ['r2', 'r3'],
             id(tree2.children[0]): ['r1']
         }
-        assert compiled_css.mapping == expected_mapping
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css.mapping) == expected_mapping
 
     def test_rules_numbered_in_order(self):
         """Test that rules are numbered in lexicographical order"""
@@ -174,14 +210,15 @@ class TestCompileCSS:
             ]
         )
         compiled_css = compile_css(tree)
-        expected_rules = {
-            'r0': {'a': '10'},
-            'r1': {'a': '5'},
-            'r2': {'b': '10'},
-            'r3': {'b': '4'},
-            'r4': {'c': '5'}
-        }
-        assert compiled_css.rules == expected_rules
+        expected_rules = [
+            {"name": "r0", "declarations": {"a": "10"}},
+            {"name": "r1", "declarations": {"a": "5"}},
+            {"name": "r2", "declarations": {"b": "10"}},
+            {"name": "r3", "declarations": {"b": "4"}},
+            {"name": "r4", "declarations": {"c": "5"}},
+        ]
+        assert TestCompileCSS._serialize_rules(
+            compiled_css.rules) == expected_rules
 
     def test_duplicate_node(self):
         """Test that adding the same node twice does not impact compilation"""
@@ -193,11 +230,11 @@ class TestCompileCSS:
                 HTMLNode(style={"b": "10"}),
             ]
         )
-        expected_rules = {
-            'r0': {'a': '5'},
-            'r1': {'b': '10'},
-            'r2': {'b': '4'}
-        }
+        expected_rules = [
+            {"name": "r0", "declarations": {"a": "5"}},
+            {"name": "r1", "declarations": {"b": "10"}},
+            {"name": "r2", "declarations": {"b": "4"}}
+        ]
         expected_mapping = {
             id(tree): ['r0', 'r2'],
             id(tree.children[0]): ['r0'],
@@ -206,8 +243,10 @@ class TestCompileCSS:
         compiled_css = compile_css([tree])
         assert compiled_css.trees == [tree]
         assert [id(t) for t in compiled_css.trees] == [id(tree)]
-        assert compiled_css.rules == expected_rules
-        assert compiled_css.mapping == expected_mapping
+        assert TestCompileCSS._serialize_rules(
+            compiled_css.rules) == expected_rules
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css.mapping) == expected_mapping
 
         # Compiling the tree and one of its children, which should already be
         # included recursively from the tree itself and should not affect the
@@ -216,25 +255,41 @@ class TestCompileCSS:
         assert compiled_css2.trees == [tree, tree.children[0]]
         assert [id(t) for t in compiled_css2.trees] == [
             id(tree), id(tree.children[0])]
-        assert compiled_css2.rules == expected_rules
-        assert compiled_css2.mapping == expected_mapping
+        assert TestCompileCSS._serialize_rules(
+            compiled_css2.rules) == expected_rules
+        assert TestCompileCSS._serialize_mapping(
+            compiled_css2.mapping) == expected_mapping
+
+    @pytest.mark.parametrize("rule_namer, names", [
+        (lambda _, i: f"rule{i}", ["rule0", "rule1", "rule2"]),
+        (lambda _, i: f"rule-{i + 1}", ["rule-1", "rule-2", "rule-3"]),
+        (lambda r, i: f"{list(r[i].declarations.items())[0][0]}{i}", [
+            "az0", "bz1", "bz2"]),
+        (lambda r, i: f"{list(r[i].declarations.items())[0][0][0]}{i}", [
+            "a0", "b1", "b2"]),
+        (lambda r, i: f"r{list(r[i].declarations.items())[0][1]}-{i}", [
+            "r10-1", "r4-2", "r5-0"]),
+    ])
+    def test_custom_rule_names(self, rule_namer, names):
+        tree = HTMLNode(
+            style={"az": "5", "bz": "4"},
+            children=[
+                HTMLNode(style={"az": "5"}),
+                HTMLNode(style={"bz": "10"}),
+            ]
+        )
+        compiled_css = compile_css(tree, rule_namer=rule_namer)
+        assert [r.name for r in compiled_css.rules] == names
 
 
 class TestCompiledCSS:
     def test_export_custom_compiled_css(self):
-        rules = {
-            "r0": {
-                "margin": "0",
-                "padding": "0"
-            },
-            "r1": {
-                "color": "blue"
-            },
-            "r2": {
-                "background-color": "white",
-                "font-size": "16px"
-            }
-        }
+        rules = [
+            CSSRule(name="r0", declarations={"margin": "0", "padding": "0"}),
+            CSSRule(name="r1", declarations={"color": "blue"}),
+            CSSRule(name="r2", declarations={
+                    "background-color": "white", "font-size": "16px"})
+        ]
         compiled_css = CompiledCSS(trees=None,
                                    rules=rules,
                                    mapping=None)
@@ -364,12 +419,12 @@ class TestApplyCSS:
 
         # Compiling and applying CSS to the tree
         compiled_css = compile_css(tree)
-        assert compiled_css.rules == {
-            "r0": {"color": "blue"},
-            "r1": {"color": "green"},
-            "r2": {"margin": "0"},
-            "r3": {"padding": "0"}
-        }
+        assert TestCompileCSS._serialize_rules(compiled_css.rules) == [
+            {"name": "r0", "declarations": {"color": "blue"}},
+            {"name": "r1", "declarations": {"color": "green"}},
+            {"name": "r2", "declarations": {"margin": "0"}},
+            {"name": "r3", "declarations": {"padding": "0"}}
+        ]
         apply_css(compiled_css, tree)
 
         # Checking the tree's new classes
@@ -398,7 +453,7 @@ class TestApplyCSS:
         )
         html_before = tree.to_html()
         compiled_css = compile_css(tree)
-        assert compiled_css.rules == {}
+        assert compiled_css.rules == []
         apply_css(compiled_css, tree)
         html_after = tree.to_html()
 
@@ -475,3 +530,23 @@ class TestApplyCSS:
         apply_css(compiled_css, tree)
         assert "class" not in tree.attributes
         assert tree.to_html() == '<htmlnode></htmlnode>'
+
+
+class TestDefaultRuleNamer:
+    def test_default_rule_namer(self):
+        rules = [CSSRule(None, {"color": "red"}),
+                 CSSRule(None, {"margin": "0"})]
+        for i, rule in enumerate(rules):
+            rule.name = default_rule_namer(rules=rules, index=i)
+        assert rules[0].name == "r0"
+        assert rules[1].name == "r1"
+
+    def test_default_rule_namer_override(self):
+        rules = [CSSRule("first", {"color": "red"}),
+                 CSSRule("second", {"margin": "0"})]
+        assert rules[0].name == "first"
+        assert rules[1].name == "second"
+        for i, rule in enumerate(rules):
+            rule.name = default_rule_namer(rules=rules, index=i)
+        assert rules[0].name == "r0"
+        assert rules[1].name == "r1"

webwidgets-0.2.1/tests/utility/test_representation.py

@@ -0,0 +1,118 @@
+# =======================================================================
+#
+#  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 webwidgets.utility.representation import ReprMixin
+
+
+class TestRepresentation:
+    def test_repr_without_attributes(self):
+        """Test case without any attributes"""
+        class EmptyClass(ReprMixin):
+            pass
+        empty_obj = EmptyClass()
+        assert str(empty_obj) == "EmptyClass()"
+
+    def test_repr_with_none_value(self):
+        """Test case with None value for an attribute"""
+        class MyClass(ReprMixin):
+            def __init__(self, a, b=None):
+                self.a = a
+                self.b = b
+        obj = MyClass(1)
+        assert str(obj) == "MyClass(a=1, b=None)"
+
+    def test_repr_with_multiple_attributes(self):
+        """Test case with multiple attributes"""
+        class ComplexClass(ReprMixin):
+            def __init__(self, a, b, c=None, d=None):
+                self.a = a
+                self.b = b
+                self.c = c
+                self.d = d
+        obj = ComplexClass(1, 2, c=3, d=4)
+        assert str(obj) == "ComplexClass(a=1, b=2, c=3, d=4)"
+
+    def test_repr_with_multiple_types(self):
+        """Test case with multiple types of attributes"""
+        class MixedTypeClass(ReprMixin):
+            def __init__(self, a: int, b: float, c: str):
+                self.a = a
+                self.b = b
+                self.c = c
+        obj = MixedTypeClass(1, 2.5, "test")
+        assert str(obj) == "MixedTypeClass(a=1, b=2.5, c='test')"
+
+    def test_repr_with_large_number_of_attributes(self):
+        """Test case with a large number of attributes"""
+        class LargeObject(ReprMixin):
+            def __init__(self, **kwargs):
+                for k, v in kwargs.items():
+                    setattr(self, k, v)
+        obj = LargeObject(a=1, b=2, c=3, d=4, e=5, f=6, g=7, h=8, i=9, j=10)
+        assert str(
+            obj) == "LargeObject(a=1, b=2, c=3, d=4, e=5, f=6, g=7, h=8, i=9, j=10)"
+
+    def test_repr_with_nested_objects(self):
+        """Test case with nested object as attribute"""
+        class Inner(ReprMixin):
+            def __init__(self, a, b):
+                self.a = a
+                self.b = b
+
+        class Outer(ReprMixin):
+            def __init__(self, obj=None):
+                self.obj = obj
+        complex_obj = Outer(obj=Inner(a=1, b=2))
+        assert str(complex_obj) == "Outer(obj=Inner(a=1, b=2))"
+
+    def test_repr_with_nested_list(self):
+        """Test case with list of objects as attribute"""
+        class Inner(ReprMixin):
+            def __init__(self, a):
+                self.a = a
+
+        class Outer(ReprMixin):
+            def __init__(self):
+                self.obj = [Inner(1), Inner(2)]
+        obj = Outer()
+        assert str(obj) == "Outer(obj=[Inner(a=1), Inner(a=2)])"
+
+    def test_repr_with_nested_dict(self):
+        """Test case with list of objects as attribute"""
+        class Inner(ReprMixin):
+            def __init__(self, a):
+                self.a = a
+
+        class Outer(ReprMixin):
+            def __init__(self):
+                self.d = {
+                    "1": Inner(1),
+                    "2": Inner(2)
+                }
+        obj = Outer()
+        assert str(obj) == "Outer(d={'1': Inner(a=1), '2': Inner(a=2)})"
+
+    def test_repr_with_nested_dict_of_list(self):
+        """Test case with dict containing list of objects as attribute"""
+        class Inner(ReprMixin):
+            def __init__(self, a):
+                self.a = a
+
+        class Outer(ReprMixin):
+            def __init__(self):
+                self.d = {
+                    "odd": [Inner(1), Inner(3)],
+                    "even": [Inner(2)]
+                }
+        obj = Outer()
+        assert str(obj) == "Outer(d={'odd': [Inner(a=1), " \
+            "Inner(a=3)], 'even': [Inner(a=2)]})"

{webwidgets-0.2.0 → webwidgets-0.2.1}/tests/utility/test_validation.py

@@ -78,6 +78,23 @@ class TestValidate:
         with pytest.raises(ValueError, match=re.escape(', '.join(chars))):
             validate_css_identifier(f"my-class-{chars}")
 
+    @pytest.mark.parametrize("code, chars, raise_on_start", [
+        # Injection in rule name
+        ("rule{}custom-code", "{, }", False),
+        ("rule {}custom-code", "  , {, }", False),
+
+        # Injection in property name
+        ("}custom-code", None, True),
+        ("} custom-code", None, True),
+        ("url(\"somewhere.com\")", "(, \", ., \", )", False),
+    ])
+    def test_code_injection_in_css_identifier(self, code, chars, raise_on_start):
+        """Test that code injected into CSS identifier raises an exception"""
+        match = (r"must start with.*:.*" + code) if raise_on_start else \
+            (r"Invalid character\(s\).*" + re.escape(chars))
+        with pytest.raises(ValueError, match=match):
+            validate_css_identifier(code)
+
     def test_valid_html_classes(self):
         """Test that valid HTML class attributes are accepted"""
         validate_html_class("")
@@ -108,6 +125,23 @@ class TestValidate:
         with pytest.raises(ValueError, match="must start with"):
             validate_html_class("my-class123 -er4 my-other-class")
 
+    @pytest.mark.parametrize("code, chars, raise_on_start", [
+        # Exception are raised on first offending class before space
+        (">custom-code", None, True),
+        ("\">custom-code", None, True),
+        ("c>custom-code", ">", False),
+        ("c\">custom-code", "\", >", False),
+        ("c\"> custom-code", "\", >", False),
+        ("c\">custom-code<div class=\"", "\", >, <", False),
+        ("c\"><script src=\"file.js\"></script>", "\", >, <", False),
+    ])
+    def test_code_injection_in_html_class(self, code, chars, raise_on_start):
+        """Test that HTML code injected into class attribute raises an exception"""
+        match = (r"must start with.*:.*" + code) if raise_on_start else \
+            (r"Invalid character\(s\).*" + re.escape(chars))
+        with pytest.raises(ValueError, match=match):
+            validate_html_class(code)
+
     @pytest.mark.parametrize("class_in, valid", [
         (None, True),
         ("", True),
@@ -123,7 +157,7 @@ class TestValidate:
     ])
     @pytest.mark.parametrize("add_r2_in", [False, True])
     def test_validation_within_apply_css(self, class_in, valid, add_r2_in):
-        """Tests that valid class attributes make it through rendering"""
+        """Tests that valid class attributes make it through HTML rendering"""
         # Compiling and applying CSS to a tree
         c_in = None if class_in is None else ' '.join(
             ([class_in] if class_in else []) + (["r2"] if add_r2_in else []))
@@ -152,3 +186,33 @@ class TestValidate:
                 tree.validate_attributes()
             with pytest.raises(ValueError):
                 tree.to_html()
+
+    @pytest.mark.parametrize("rule_namer, valid", [
+        (None, True),  # Default rule namer
+        (lambda _, i: f"rule{i}", True),
+        (lambda _, i: f"r-{i + 1}", True),
+        (lambda _, i: f"--r-{i + 1}", True),
+        (lambda r, i: f"{list(r[i].declarations.items())[0][0][0]}{i}", True),
+        (lambda _, i: str(i), False),  # Starts with digit
+        (lambda _, i: f"-r{i}", False),  # Starts with single hyphen
+        (lambda _, i: f"rule {i + 1}", False),  # Invalid character (space)
+        (lambda _, i: f"r={i}", False),  # Invalid character (=)
+        (lambda r, i: f"{list(r[i].declarations.items())[0]}",
+         False),  # Invalid characters (comma...)
+        (lambda _, i: f"r{i}" + "{}custom-code", False),  # Code injection
+    ])
+    def test_validation_within_to_css(self, rule_namer, valid):
+        """Tests that valid class attributes make it through CSS rendering"""
+        tree = HTMLNode(
+            style={"az": "5", "bz": "4"},
+            children=[
+                HTMLNode(style={"az": "5"}),
+                HTMLNode(style={"bz": "10"}),
+            ]
+        )
+        compiled_css = compile_css(tree, rule_namer=rule_namer)
+        if valid:
+            compiled_css.to_css()
+        else:
+            with pytest.raises(ValueError):
+                compiled_css.to_css()

{webwidgets-0.2.0 → webwidgets-0.2.1}/webwidgets/__init__.py

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

{webwidgets-0.2.0 → webwidgets-0.2.1}/webwidgets/compilation/css/__init__.py

@@ -10,4 +10,5 @@
 #
 # =======================================================================
 
-from .css import compile_css, CompiledCSS, apply_css
+from .css import compile_css, CSSRule, CompiledCSS, apply_css, \
+    default_rule_namer

{webwidgets-0.2.0 → webwidgets-0.2.1}/webwidgets/compilation/css/css.py

@@ -11,31 +11,49 @@
 # =======================================================================
 
 import itertools
-from typing import Dict, List, Union
+from typing import Callable, Dict, List, Union
 from webwidgets.compilation.html.html_node import HTMLNode
+from webwidgets.utility.representation import ReprMixin
 from webwidgets.utility.validation import validate_css_identifier
 
 
-class CompiledCSS:
+class CSSRule(ReprMixin):
+    """A rule in a style sheet.
+    """
+
+    def __init__(self, name: str, declarations: Dict[str, str]):
+        """Stores the name and declarations of the rule.
+
+        :param name: The name of the rule.
+        :type name: str
+        :param declarations: The CSS declarations for the rule, specified as a
+            dictionary where keys are property names and values are their
+            corresponding values. For example: `{'color': 'red'}`
+        :type declarations: Dict[str, str]
+        """
+        super().__init__()
+        self.name = name
+        self.declarations = declarations
+
+
+class CompiledCSS(ReprMixin):
     """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]]):
+    def __init__(self, trees: List[HTMLNode], rules: List[CSSRule],
+                 mapping: Dict[int, List[CSSRule]]):
         """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 rules: The compiled CSS rules.
+        :type rules: List[CSSRule]
         :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]]
+            that achieve the same style.
+        :type mapping: Dict[int, List[CSSRule]]
         """
+        super().__init__()
         self.trees = trees
         self.rules = rules
         self.mapping = mapping
@@ -44,9 +62,9 @@ class CompiledCSS:
         """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.
+        Rule names are converted to class selectors. Note that each rule and
+        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.
@@ -58,10 +76,11 @@ class CompiledCSS:
         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():
+        # Writing down each rule
+        for i, rule in enumerate(self.rules):
+            validate_css_identifier(rule.name)
+            css_code += f".{rule.name}" + " {\n"
+            for property_name, value in rule.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 '')
@@ -69,7 +88,9 @@ class CompiledCSS:
         return css_code
 
 
-def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
+def compile_css(trees: Union[HTMLNode, List[HTMLNode]],
+                rule_namer: Callable[[List[CSSRule], int],
+                                     str] = None) -> CompiledCSS:
     """Computes optimized CSS rules from the given HTML trees.
 
     The main purpose of this function is to reduce the number of CSS rules
@@ -97,15 +118,31 @@ def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
 
         >>> compiled_css = compile_css(tree)
         >>> print(compiled_css.rules)
-        {
-            'r0': {'color': 'blue'},
-            'r1': {'margin': '0'},
-            'r2': {'padding': '0'}
-        }
+        [
+            CSSRule(name='r0', declarations={'color': 'blue'}),
+            CSSRule(name='r1', declarations={'margin': '0'}),
+            CSSRule(name='r2', declarations={'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]]
+    :param rule_namer: A callable that takes two arguments, which are the list
+        of all compiled rules and an index within that list, and returns a
+        unique name for the rule at the given index.
+
+        This argument allows to customize the rule naming process and use names
+        other than the default `"r0"`, `"r1"`, etc. For example, it can be used
+        to achieve something similar to Tailwind CSS and name rules according
+        to what they achieve, e.g. by prefixing their name with `"m"` for
+        margin rules or `"p"` for padding rules. Note that all rule names will
+        be validated with the :py:func:`validate_css_identifier` function
+        before being written into CSS code.
+
+        Defaults to the :py:func:`default_rule_namer` function which implements
+        a default naming strategy where each rule is named `"r{i}"` where `i`
+        is the index of the rule in the list.
+    :type rule_namer: Callable[[List[CSSRule], int], str]
     :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
@@ -117,14 +154,21 @@ def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
     if isinstance(trees, HTMLNode):
         trees = [trees]
 
+    # Handling default rule_namer
+    rule_namer = default_rule_namer if rule_namer is None else rule_namer
+
     # 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())])
+    rules = [CSSRule(None, dict([p]))  # Initializing with no name
+             for p in sorted(properties)]
+    for i, rule in enumerate(rules):  # Assigning name from callback
+        rule.name = rule_namer(rules, i)
+    rules = sorted(rules, key=lambda r: r.name)  # Sorting by name
+    mapping = {node_id: [r for r in rules if
+                         set(r.declarations.items()).issubset(style.items())]
                for node_id, style in styles.items()}
     return CompiledCSS(trees, rules, mapping)
 
@@ -156,7 +200,7 @@ def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
 
         # 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
+        rules_to_add = [r.name for r in css.mapping[id(tree)] if r.name not in
                         tree.attributes.get('class', '').split(' ')]
 
         # Updating the class attribute. If it already exists and is not empty,
@@ -169,3 +213,17 @@ def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
     # Recursively applying the CSS rules to all child nodes of the tree
     for child in tree.children:
         apply_css(css, child)
+
+
+def default_rule_namer(rules: List[CSSRule], index: int) -> str:
+    """Default rule naming function. Returns a string like "r{i}" where {i} is
+    the index of the rule.
+
+    :param rules: List of all compiled CSSRule objects. This argument is not
+        used in this function, but it can be used in other naming strategies.
+    :type rules: List[CSSRule]
+    :param index: Index of the rule being named.
+    :type index: int
+    :return: A string like `"r{i}"` where `i` is the index of the rule.
+    """
+    return f'r{index}'

{webwidgets-0.2.0 → webwidgets-0.2.1}/webwidgets/compilation/html/html_node.py

@@ -13,11 +13,12 @@
 import copy
 import itertools
 from typing import Any, Dict, List, Union
+from webwidgets.utility.representation import ReprMixin
 from webwidgets.utility.sanitizing import sanitize_html_text
 from webwidgets.utility.validation import validate_html_class
 
 
-class HTMLNode:
+class HTMLNode(ReprMixin):
     """Represents an HTML node (for example, a div or a span).
     """
 
@@ -34,6 +35,7 @@ class HTMLNode:
         :param style: Dictionary of CSS properties for the node. Defaults to an empty dictionary.
         :type style: Dict[str, str]
         """
+        super().__init__()
         self.children = [] if children is None else children
         self.attributes = {} if attributes is None else attributes
         self.style = {} if style is None else style

{webwidgets-0.2.0 → webwidgets-0.2.1}/webwidgets/utility/__init__.py

@@ -10,5 +10,6 @@
 #
 # =======================================================================
 
+from .representation import *
 from .sanitizing import *
 from .validation import *

webwidgets-0.2.1/webwidgets/utility/representation.py

@@ -0,0 +1,34 @@
+# =======================================================================
+#
+#  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
+#
+# =======================================================================
+
+class ReprMixin:
+    """A mixin class that is represented with its variables when printed.
+
+    For example:
+
+    >>> class MyClass(RepresentedWithVars):
+    ...     def __init__(self, a, b):
+    ...         self.a = a
+    ...         self.b = b
+    >>> obj = MyClass(1, 2)
+    >>> print(obj)
+    MyClass(a=1, b=2)
+    """
+
+    def __repr__(self) -> str:
+        """Returns a string exposing all member variables of the class.
+
+        :return: A string representing the class with its variables.
+        :rtype: str
+        """
+        variables = ', '.join(f'{k}={repr(v)}' for k, v in vars(self).items())
+        return f"{self.__class__.__name__}({variables})"