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

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/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/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/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/utility/__init__.py

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

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})"

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

@@ -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.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+webwidgets/__init__.py,sha256=lWweaTCcPhSUa2zi5l7UnoDSgup_q81dh0pn_kGYYT0,481
+webwidgets/compilation/__init__.py,sha256=hb61nhmPTghIzuA_hun98xT5Ngv7QFAgMHD44g-9uOo,433
+webwidgets/compilation/css/__init__.py,sha256=ZisiFaw9RqNuVqewOjnEOLLLZwgjfW95yruMXGRGp_I,484
+webwidgets/compilation/css/css.py,sha256=msFTyuIjEvLTKk4H-tvvr9HK1K6N-_hcF1pmOJWT1S8,9654
+webwidgets/compilation/html/__init__.py,sha256=NRccbCUKdhmK51MnYFO8q1sS8fWhAggRnMiGDG7lQMQ,505
+webwidgets/compilation/html/html_node.py,sha256=QptDwSD2ljzR5S-r5rXuRBeOz8EF55OlZlWTXgQzI4Y,10189
+webwidgets/compilation/html/html_tags.py,sha256=U2HmhLkV6BOqTmgvIMlmMCQysQ7i2nEAVWJzZe74ucA,1388
+webwidgets/utility/__init__.py,sha256=nY-j5tu45qGl09lRyMyxkT4zsUf2jCfeXWcx954yIvM,478
+webwidgets/utility/representation.py,sha256=lQ15v_DZOHBQKLM8pzRE1tuJkU_modhPTpWpSJ2lBCE,1061
+webwidgets/utility/sanitizing.py,sha256=OKJRDqk-OXYCWeK6ie3GdfQvb49wTs93kd971mg5oK0,5770
+webwidgets/utility/validation.py,sha256=bUjpiGP59GW3DPvQ1hwR5ezBMmcSd6v4xlDLwTHZv_A,4261
+webwidgets-0.2.1.dist-info/METADATA,sha256=Adl61Eg47Lw7AuZ5sJN_9-MMumjgsEVFZ33glOceGUk,550
+webwidgets-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+webwidgets-0.2.1.dist-info/licenses/LICENSE,sha256=LISw1mw5eK6i8adFSlx6zltZxrJFwurngVdZAEU8g_I,1064
+webwidgets-0.2.1.dist-info/RECORD,,

webwidgets-0.2.0.dist-info/RECORD

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