webcode-tk 1.2.12__tar.gz → 1.2.18__tar.gz

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webcode-tk
-Version: 1.2.12
+Version: 1.2.18
 Summary: A set of tools for inspecting HTML and CSS code
 License: MIT
 License-File: LICENSE.rst
@@ -23,6 +23,7 @@ Requires-Dist: mechanicalsoup (>=1.4.0,<2.0.0)
 Requires-Dist: nltk (>=3.8.1,<4.0.0)
 Requires-Dist: pre-commit (>=4.5.0,<5.0.0)
 Requires-Dist: py-readability-metrics (>=1.4.5,<2.0.0)
+Requires-Dist: pytest (>=9.0.3,<10.0.0)
 Requires-Dist: pytest-mock (>=3.15.1,<4.0.0)
 Requires-Dist: requests (>=2.28.1,<3.0.0)
 Requires-Dist: textatistic (>=0.0.1,<0.0.2)

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "webcode-tk"
-version = "1.2.12"
+version = "1.2.18"
 description = "A set of tools for inspecting HTML and CSS code"
 authors = ["hundredvisionsguy <cwinikka@gmail.com>"]
 keywords = ["html", "validation", "css", ]
@@ -28,6 +28,7 @@ lxml = "^6.0.0"
 mechanicalsoup = "^1.4.0"
 pytest-mock = "^3.15.1"
 pre-commit = "^4.5.0"
+pytest = "^9.0.3"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "*"

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/__init__.py

@@ -40,4 +40,4 @@
 - **`validator_tools`**: sends HTML or CSS code to the W3C Validator to check
           for errors.
 """
-__version__ = "1.2.12"
+__version__ = "1.2.18"

webcode_tk-1.2.18/webcode_tk/_style_inheritance.py

@@ -0,0 +1,371 @@
+"""
+_style_inheritance.py
+By Chris Winikka
+
+Internal utiliities for computing CSS inheritance.
+
+This module provides optimized functions for computing CSS inheritance and
+visual background inheritance during contrast analysis. It is used internally
+by contrast_tools and is not part of the public API.
+
+Functions:
+    apply_css_inheritance: Apply inheritable CSS properties top-down through
+        DOM.
+    apply_visual_background_inheritance: Propagate background colors via
+        ancestry.
+    find_ancestor_background: Locate first ancestor with explicit background.
+    apply_inheritance: Wrapper combining CSS and visual inheritance.
+"""
+
+import re
+
+from bs4 import Tag
+
+DEFAULT_GLOBAL_BACKGROUND = "#ffffff"
+
+
+def apply_css_inheritance(computed_styles: dict) -> None:
+    """
+    Apply CSS inheritance top-down (parent to children) instead of bottom-up.
+
+    This is MUCH faster than walking up the tree for each element.
+    O(n) instead of O(n*m*h) where n=elements, m=properties, h=tree_depth
+    """
+    inheritable_props = {"color", "font-size", "font-weight"}
+
+    # Build parent-child relationships
+    parent_to_children = {}
+    child_to_parent = {}
+
+    for element in computed_styles:
+        parent = element.parent
+        if parent and parent in computed_styles:
+            if parent not in parent_to_children:
+                parent_to_children[parent] = []
+            parent_to_children[parent].append(element)
+            child_to_parent[element] = parent
+
+    # Process top-down: parent values flow to children
+    visited = set()
+
+    def traverse_tree(element, inherited_props_from_ancestors):
+        """DFS traversal pushing inherited values down."""
+        if element in visited:
+            return
+        visited.add(element)
+
+        if element not in computed_styles:
+            return
+
+        element_styles = computed_styles[element]
+        props_for_children = inherited_props_from_ancestors.copy()
+
+        # For each inheritable property
+        for prop in inheritable_props:
+            current_prop = element_styles.get(prop)
+
+            # If element has explicit rule, use it (don't inherit)
+            if current_prop and current_prop.get("source") == "rule":
+                props_for_children[prop] = current_prop
+            # Otherwise inherit from ancestor if available
+            elif prop in inherited_props_from_ancestors:
+                inherited_value = inherited_props_from_ancestors[prop]
+                element_styles[prop] = {
+                    "value": inherited_value["value"],
+                    "specificity": inherited_value["specificity"],
+                    "source": "inheritance",
+                    "selector": inherited_value.get("selector", "inherited"),
+                    "css_file": inherited_value.get("css_file"),
+                    "css_source_type": inherited_value.get("css_source_type"),
+                    "inherited_from": child_to_parent.get(element),
+                }
+                # Also pass inherited value to children
+                props_for_children[prop] = element_styles[prop]
+
+        # Recurse to children with updated inherited values
+        if element in parent_to_children:
+            for child in parent_to_children[element]:
+                traverse_tree(child, props_for_children)
+
+    # Start traversal from root elements (with no parent in computed_styles)
+    for element in computed_styles:
+        if element not in child_to_parent:
+            # This is a root element
+            traverse_tree(element, {})
+
+
+def apply_visual_background_inheritance(computed_styles: dict) -> None:
+    """
+    Apply visual background colors to elements without explicit backgrounds.
+
+    Args:
+        computed_styles: a dictionary of elements with computed styles.
+    Returns:
+        None
+    """
+
+    for element in computed_styles:
+        element_styles = computed_styles[element]
+
+        # Check for BOTH background-color AND background
+        current_bg = element_styles.get("background-color")
+        has_background_shorthand = "background" in element_styles
+
+        # If element has background shorthand, process it for images
+        if has_background_shorthand:
+            bg_value = element_styles["background"]["value"]
+
+            # Check if background contains a raster image
+            if contains_raster_image(bg_value):
+                # Mark as contrast-indeterminate - cannot analyze
+                element_styles["background-color"] = {
+                    "value": None,
+                    "specificity": "000",
+                    "contrast_analysis": "indeterminate",
+                    "reason": "background_image_blocks_color_analysis",
+                    "original_background": bg_value,
+                    "visual_inheritance": False,
+                }
+                continue
+            else:
+                # Has usable background shorthand - skip inheritance
+                continue
+        if not current_bg:
+            continue
+
+        bg_source = current_bg.get("source")
+        bg_value = current_bg.get("value")
+
+        # Skip elements with explicit CSS rules
+        if bg_source == "rule":
+            continue
+
+        # Only update elements that still have the default white background
+        # This prevents overwriting elements with existing proper backgrounds
+        if bg_source != "default":
+            continue
+
+        # Element needs background inheritance (lines 1120-1141)
+        ancestor_bg = find_ancestor_background(element, computed_styles)
+
+        if not ancestor_bg or ancestor_bg.get("source") == "default":
+            # No explicit background to inherit - keep browser default
+            continue
+
+        if ancestor_bg.get("contrast_analysis") == "indeterminate":
+            # Ancestor is indeterminate - propagate that status
+            element_styles["background-color"] = {
+                "value": None,
+                "specificity": "000",
+                "contrast_analysis": "indeterminate",
+                "reason": ancestor_bg["reason"],
+                "inherited_from": ancestor_bg["source_element"],
+                "source": "visual_inheritance",
+                "original_background": ancestor_bg.get("original_background"),
+            }
+
+        else:
+            # Normal inheritance - extract usable color
+            contrast_color = extract_contrast_color(ancestor_bg["value"])
+            effective_color = (
+                contrast_color if contrast_color else ancestor_bg["value"]
+            )
+            element_styles["background-color"] = {
+                "value": effective_color,
+                "specificity": "000",
+                "source": "visual_inheritance",
+                "inherited_from": ancestor_bg["source_element"],
+                "contrast_analysis": "determinable",
+                "original_background": (
+                    ancestor_bg["value"]
+                    if ancestor_bg["value"] != DEFAULT_GLOBAL_BACKGROUND
+                    else None
+                ),
+            }
+
+
+def contains_raster_image(background_value: str) -> bool:
+    """Check if background contains a raster image that blocks color analysis.
+
+    Args:
+        background_value: the css value applied to the background property.
+
+    Returns:
+        bool: whether the background value includes a raster image or not.
+    """
+    # Add None check
+    if background_value is None:
+        return False
+
+    return bool(
+        re.search(
+            r"url\([^)]*\.(jpg|jpeg|png|gif|webp|bmp)", background_value, re.I
+        )
+    )
+
+
+def extract_contrast_color(background_value: str) -> str:
+    """
+    Extract usable color for contrast analysis, or None.
+
+    Args:
+        background_value (str): CSS background property value.
+
+    Returns:
+        str: Color value suitable for contrast analysis, or None if no
+            usable color found.
+    """
+    # Add None check at the beginning
+    if background_value is None:
+        return None
+
+    # Remove raster images - they block color visibility
+    if re.search(
+        r"url\([^)]*\.(jpg|jpeg|png|gif|webp|bmp)", background_value, re.I
+    ):
+        return None
+
+    # Handle gradients - extract representative color
+    if "gradient" in background_value.lower():
+        return extract_gradient_contrast_color(background_value)
+
+    # Handle solid colors
+    re_pattern = r"(#[a-f0-9]{3,6}|rgb\([^)]+\)|rgba\([^)]+\)|hsl\([^)]+\)|"
+    re_pattern += r"hsla\([^)]+\)|[a-z]+)"
+    color_match = re.search(
+        re_pattern,
+        background_value,
+        re.I,
+    )
+    return color_match.group(1) if color_match else None
+
+
+def find_ancestor_background(element: Tag, computed_styles: dict) -> dict:
+    """
+    Walk up DOM tree to find first ancestor with background.
+
+    Args:
+        element (Tag): BeautifulSoup Tag object to start searching from.
+        computed_styles (dict): Dictionary mapping elements to their
+            computed styles.
+
+    Returns:
+        dict: Dictionary containing 'value' (background color) and
+            'source_element' (ancestor element or None).
+    """
+    current = element.parent
+
+    while current:
+        if current in computed_styles:
+            current_styles = computed_styles[current]
+
+            # Flag to track if we should skip this ancestor
+            skip_ancestor = False
+
+            # Check for background-color or background
+            for bg_prop in ["background-color", "background"]:
+                if bg_prop in current_styles:
+                    bg_source = current_styles[bg_prop].get("source")
+
+                    # Skip elements that only have visual inheritance
+                    if bg_source == "visual_inheritance":
+                        skip_ancestor = True
+                        break  # ✅ Break out of property loop
+
+                    # Accept both "rule" and "default" sources
+                    if bg_source in ["rule", "default"]:
+                        bg_value = current_styles[bg_prop]["value"]
+                        if bg_source == "default":
+                            # Skip ancestors with only default backgrounds
+                            skip_ancestor = True
+                            break
+
+                        # Does this ancestor already is indeterminate status
+                        if (
+                            current_styles[bg_prop].get("contrast_analysis")
+                            == "indeterminate"
+                        ):
+                            return {
+                                "value": None,
+                                "source_element": current,
+                                "contrast_analysis": "indeterminate",
+                                "reason": "ancestor_has_background_image",
+                                "original_background": current_styles[
+                                    bg_prop
+                                ].get("original_background", bg_value),
+                            }
+
+                        # Skip None values and continue searching
+                        if bg_value is None:
+                            continue  # Continue to next property
+
+                        # Check if this background contains a raster image
+                        if contains_raster_image(bg_value):
+                            return {
+                                "value": None,
+                                "source_element": current,
+                                "contrast_analysis": "indeterminate",
+                                "reason": "ancestor_has_background_image",
+                                "original_background": bg_value,
+                            }
+
+                        # Found explicit background
+                        bg_items = current_styles[bg_prop].items()
+                        return {
+                            "value": bg_value,
+                            "source_element": current,
+                            "contrast_analysis": "determinable",
+                            # Copy metadata from ancestor
+                            **{
+                                metadata_key: metadata_value
+                                for metadata_key, metadata_value in bg_items
+                                if metadata_key not in ["value"]
+                            },
+                        }
+
+            # If we flagged this ancestor to skip, move to next ancestor
+            if skip_ancestor:
+                current = current.parent
+                continue  # ✅ Now this continues to next ancestor
+
+        current = current.parent
+
+    # No ancestor background found, use default
+    return {
+        "value": DEFAULT_GLOBAL_BACKGROUND,
+        "source_element": None,
+        "contrast_analysis": "determinable",
+        "source": "default",
+    }
+
+
+def extract_gradient_contrast_color(background_value: str) -> str:
+    """
+    Extract representative color from gradient for contrast analysis.
+
+    Args:
+        background_value (str): CSS gradient value (e.g.,
+            'linear-gradient(red, blue)').
+
+    Returns:
+        str: Representative color for contrast analysis, or None if no
+            color found.
+    """
+    # Add None check
+    if background_value is None:
+        return None
+
+    # Strategy: Use the final color in gradient (most visible for reading)
+    # This handles: linear-gradient(red, blue) -> blue
+    #              radial-gradient(center, red, blue) -> blue
+
+    # Find all colors in gradient
+    color_pattern = r"(#[a-f0-9]{3,6}|rgb\([^)]+\)|rgba\([^)]+\)|"
+    color_pattern += r"hsl\([^)]+\)|hsla\([^)]+\)|[a-z]+)"
+    colors = re.findall(color_pattern, background_value, re.I)
+
+    if colors:
+        # Use last color (end of gradient)
+        return colors[-1]
+
+    return None

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/animation_tools.py

@@ -2,6 +2,7 @@
 A group of functions that work with css_tools and cascade_tools to provide
 reports on CSS animations.
 """
+
 from collections.abc import Iterable
 from typing import Union
 

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/cascade_tools.py

@@ -8,6 +8,7 @@ all styles applied to every element on the page.
 With that, it scans each stylesheet and applies each style one at a time
 to all elements and their children (if applicable) of a page.
 """
+
 import ctypes
 import re
 from collections import abc

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/color_keywords.py

@@ -231,7 +231,7 @@ def is_a_keyword(word: str) -> bool:
     return is_keyword
 
 
-def get_hex_by_keyword(word: (str)) -> str:
+def get_hex_by_keyword(word: str) -> str:
     """returns the hex value of a keyword (if valid).
 
     Args:

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/color_tools.py

@@ -19,6 +19,7 @@ One thing led to another, yada yada, then I realized that this could
 be a useful tool in my web grading projects, and there you have it:
 `color_tools`.
 """
+
 import re
 
 from webcode_tk import color_keywords

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/contrast_tools.py

@@ -31,6 +31,7 @@ Constants:
         mathematical contrast ratios and size thresholds that determine WCAG
         compliance.
 """
+
 import copy
 import re
 
@@ -40,6 +41,13 @@ from bs4 import NavigableString
 from bs4 import Tag
 from file_clerk import clerk
 
+from webcode_tk._style_inheritance import (
+    apply_css_inheritance,
+    apply_visual_background_inheritance,
+    contains_raster_image,
+    DEFAULT_GLOBAL_BACKGROUND,
+    extract_contrast_color,
+)
 from webcode_tk import color_tools
 from webcode_tk import css_tools
 from webcode_tk import font_tools
@@ -49,7 +57,6 @@ from webcode_tk.font_tools import split_value_unit
 
 # Browser default styling constants
 DEFAULT_GLOBAL_COLOR = "#000000"
-DEFAULT_GLOBAL_BACKGROUND = "#ffffff"
 DEFAULT_LINK_COLOR = "#0000EE"
 DEFAULT_LINK_VISITED = "#551A8B"
 ROOT_FONT_SIZE = 16
@@ -871,12 +878,16 @@ def apply_rule_to_element(
                     "specificity": rule_specificity,
                     "source": "rule",
                     "selector": selector,
-                    "css_file": css_source_info.get("filename")
-                    if css_source_info
-                    else None,
-                    "css_source_type": css_source_info.get("source_type")
-                    if css_source_info
-                    else None,
+                    "css_file": (
+                        css_source_info.get("filename")
+                        if css_source_info
+                        else None
+                    ),
+                    "css_source_type": (
+                        css_source_info.get("source_type")
+                        if css_source_info
+                        else None
+                    ),
                 }
 
                 # Check if we should apply this font-size rule
@@ -911,12 +922,16 @@ def apply_rule_to_element(
                         "specificity": rule_specificity,
                         "source": "rule",
                         "selector": selector,
-                        "css_file": css_source_info.get("filename")
-                        if css_source_info
-                        else None,
-                        "css_source_type": css_source_info.get("source_type")
-                        if css_source_info
-                        else None,
+                        "css_file": (
+                            css_source_info.get("filename")
+                            if css_source_info
+                            else None
+                        ),
+                        "css_source_type": (
+                            css_source_info.get("source_type")
+                            if css_source_info
+                            else None
+                        ),
                         "contrast_analysis": "indeterminate",
                         "reason": "background_image_blocks_color_analysis",
                         "original_background": property_value,
@@ -933,16 +948,22 @@ def apply_rule_to_element(
                         "specificity": rule_specificity,
                         "source": "rule",
                         "selector": selector,
-                        "css_file": css_source_info.get("filename")
-                        if css_source_info
-                        else None,
-                        "css_source_type": css_source_info.get("source_type")
-                        if css_source_info
-                        else None,
+                        "css_file": (
+                            css_source_info.get("filename")
+                            if css_source_info
+                            else None
+                        ),
+                        "css_source_type": (
+                            css_source_info.get("source_type")
+                            if css_source_info
+                            else None
+                        ),
                         "contrast_analysis": "determinable",
-                        "original_background": property_value
-                        if property_value != effective_color
-                        else None,
+                        "original_background": (
+                            property_value
+                            if property_value != effective_color
+                            else None
+                        ),
                     }
 
                 # Apply specificity logic and set the property
@@ -1000,12 +1021,16 @@ def apply_rule_to_element(
                         "specificity": rule_specificity,
                         "source": "rule",
                         "selector": selector,
-                        "css_file": css_source_info.get("filename")
-                        if css_source_info
-                        else None,
-                        "css_source_type": css_source_info.get("source_type")
-                        if css_source_info
-                        else None,
+                        "css_file": (
+                            css_source_info.get("filename")
+                            if css_source_info
+                            else None
+                        ),
+                        "css_source_type": (
+                            css_source_info.get("source_type")
+                            if css_source_info
+                            else None
+                        ),
                     }
 
     return
@@ -1127,149 +1152,6 @@ def apply_inheritance(soup: BeautifulSoup, computed_styles: dict) -> None:
     apply_visual_background_inheritance(computed_styles)
 
 
-def apply_css_inheritance(computed_styles: dict) -> None:
-    """
-    Apply traditional CSS inheritance for inheritable properties.
-    Only inherit from the closest ancestor with an explicit rule.
-    """
-    inheritable_props = {"color", "font-size", "font-weight"}
-
-    for child_element in computed_styles:
-        child_styles = computed_styles[child_element]
-
-        # find closest ancestor with explicit value
-        for prop in inheritable_props:
-            child_prop = child_styles.get(prop)
-
-            # Skip if child has explicit CSS rule (not default)
-            if child_prop and child_prop.get("source") not in [
-                "default",
-                None,
-            ]:
-                continue
-
-            # Walk up tree to find first ancestor with explicit value
-            current = child_element.parent
-            inherited_value = None
-
-            while current and not inherited_value:
-                if current in computed_styles:
-                    parent_styles = computed_styles[current]
-                    parent_prop = parent_styles.get(prop)
-
-                    # Found a parent with this property
-                    if parent_prop:
-                        # Only inherit if parent has explicit rule
-                        if parent_prop.get("source") == "rule":
-                            inherited_value = parent_prop
-                            inherited_from = current
-                            break  # ← Stop at first explicit ancestor
-
-                current = current.parent
-
-            # Apply inherited value if found
-            if inherited_value:
-                child_styles[prop] = {
-                    "value": inherited_value["value"],
-                    "specificity": inherited_value["specificity"],
-                    "source": "inheritance",
-                    "selector": inherited_value.get("selector", "inherited"),
-                    "css_file": inherited_value.get("css_file"),
-                    "css_source_type": inherited_value.get("css_source_type"),
-                    "inherited_from": inherited_from,
-                }
-
-
-def apply_visual_background_inheritance(computed_styles: dict) -> None:
-    """
-    Apply visual background colors to elements without explicit backgrounds.
-
-    Args:
-        computed_styles: a dictionary of elements with computed styles.
-    Returns:
-        None
-    """
-
-    for element in computed_styles:
-        element_styles = computed_styles[element]
-
-        # Check for BOTH background-color AND background
-        current_bg = element_styles.get("background-color")
-        has_background_shorthand = "background" in element_styles
-
-        # If element has background shorthand, process it for images
-        if has_background_shorthand:
-            bg_value = element_styles["background"]["value"]
-
-            # Check if background contains a raster image
-            if contains_raster_image(bg_value):
-                # Mark as contrast-indeterminate - cannot analyze
-                element_styles["background-color"] = {
-                    "value": None,
-                    "specificity": "000",
-                    "contrast_analysis": "indeterminate",
-                    "reason": "background_image_blocks_color_analysis",
-                    "original_background": bg_value,
-                    "visual_inheritance": False,
-                }
-                continue
-            else:
-                # Has usable background shorthand - skip inheritance
-                continue
-        if not current_bg:
-            continue
-
-        bg_source = current_bg.get("source")
-        bg_value = current_bg.get("value")
-
-        # Skip elements with explicit CSS rules
-        if bg_source == "rule":
-            continue
-
-        # Only update elements that still have the default white background
-        # This prevents overwriting elements with existing proper backgrounds
-        if bg_source != "default":
-            continue
-
-        # Element needs background inheritance (lines 1120-1141)
-        ancestor_bg = find_ancestor_background(element, computed_styles)
-
-        if not ancestor_bg or ancestor_bg.get("source") == "default":
-            # No explicit background to inherit - keep browser default
-            continue
-
-        if ancestor_bg.get("contrast_analysis") == "indeterminate":
-            # Ancestor is indeterminate - propagate that status
-            element_styles["background-color"] = {
-                "value": None,
-                "specificity": "000",
-                "contrast_analysis": "indeterminate",
-                "reason": ancestor_bg["reason"],
-                "inherited_from": ancestor_bg["source_element"],
-                "source": "visual_inheritance",
-                "original_background": ancestor_bg.get("original_background"),
-            }
-
-        else:
-            # Normal inheritance - extract usable color
-            contrast_color = extract_contrast_color(ancestor_bg["value"])
-            effective_color = (
-                contrast_color if contrast_color else ancestor_bg["value"]
-            )
-            element_styles["background-color"] = {
-                "value": effective_color,
-                "specificity": "000",
-                "source": "visual_inheritance",
-                "inherited_from": ancestor_bg["source_element"],
-                "contrast_analysis": "determinable",
-                "original_background": (
-                    ancestor_bg["value"]
-                    if ancestor_bg["value"] != DEFAULT_GLOBAL_BACKGROUND
-                    else None
-                ),
-            }
-
-
 def has_usable_background_color(background_prop: dict) -> bool:
     """
     Check if background property contains usable color for contrast.
@@ -1299,193 +1181,6 @@ def has_usable_background_color(background_prop: dict) -> bool:
     )
 
 
-def contains_raster_image(background_value: str) -> bool:
-    """Check if background contains a raster image that blocks color analysis.
-
-    Args:
-        background_value: the css value applied to the background property.
-
-    Returns:
-        bool: whether the background value includes a raster image or not.
-    """
-    # Add None check
-    if background_value is None:
-        return False
-
-    return bool(
-        re.search(
-            r"url\([^)]*\.(jpg|jpeg|png|gif|webp|bmp)", background_value, re.I
-        )
-    )
-
-
-def extract_contrast_color(background_value: str) -> str:
-    """
-    Extract usable color for contrast analysis, or None.
-
-    Args:
-        background_value (str): CSS background property value.
-
-    Returns:
-        str: Color value suitable for contrast analysis, or None if no
-            usable color found.
-    """
-    # Add None check at the beginning
-    if background_value is None:
-        return None
-
-    # Remove raster images - they block color visibility
-    if re.search(
-        r"url\([^)]*\.(jpg|jpeg|png|gif|webp|bmp)", background_value, re.I
-    ):
-        return None
-
-    # Handle gradients - extract representative color
-    if "gradient" in background_value.lower():
-        return extract_gradient_contrast_color(background_value)
-
-    # Handle solid colors
-    re_pattern = r"(#[a-f0-9]{3,6}|rgb\([^)]+\)|rgba\([^)]+\)|hsl\([^)]+\)|"
-    re_pattern += r"hsla\([^)]+\)|[a-z]+)"
-    color_match = re.search(
-        re_pattern,
-        background_value,
-        re.I,
-    )
-    return color_match.group(1) if color_match else None
-
-
-def extract_gradient_contrast_color(background_value: str) -> str:
-    """
-    Extract representative color from gradient for contrast analysis.
-
-    Args:
-        background_value (str): CSS gradient value (e.g.,
-            'linear-gradient(red, blue)').
-
-    Returns:
-        str: Representative color for contrast analysis, or None if no
-            color found.
-    """
-    # Add None check
-    if background_value is None:
-        return None
-
-    # Strategy: Use the final color in gradient (most visible for reading)
-    # This handles: linear-gradient(red, blue) -> blue
-    #              radial-gradient(center, red, blue) -> blue
-
-    # Find all colors in gradient
-    color_pattern = r"(#[a-f0-9]{3,6}|rgb\([^)]+\)|rgba\([^)]+\)|"
-    color_pattern += r"hsl\([^)]+\)|hsla\([^)]+\)|[a-z]+)"
-    colors = re.findall(color_pattern, background_value, re.I)
-
-    if colors:
-        # Use last color (end of gradient)
-        return colors[-1]
-
-    return None
-
-
-def find_ancestor_background(element: Tag, computed_styles: dict) -> dict:
-    """
-    Walk up DOM tree to find first ancestor with background.
-
-    Args:
-        element (Tag): BeautifulSoup Tag object to start searching from.
-        computed_styles (dict): Dictionary mapping elements to their
-            computed styles.
-
-    Returns:
-        dict: Dictionary containing 'value' (background color) and
-            'source_element' (ancestor element or None).
-    """
-    current = element.parent
-
-    while current:
-        if current in computed_styles:
-            current_styles = computed_styles[current]
-
-            # Flag to track if we should skip this ancestor
-            skip_ancestor = False
-
-            # Check for background-color or background
-            for bg_prop in ["background-color", "background"]:
-                if bg_prop in current_styles:
-                    bg_source = current_styles[bg_prop].get("source")
-
-                    # Skip elements that only have visual inheritance
-                    if bg_source == "visual_inheritance":
-                        skip_ancestor = True
-                        break  # ✅ Break out of property loop
-
-                    # Accept both "rule" and "default" sources
-                    if bg_source in ["rule", "default"]:
-                        bg_value = current_styles[bg_prop]["value"]
-                        if bg_source == "default":
-                            # Skip ancestors with only default backgrounds
-                            skip_ancestor = True
-                            break
-
-                        # Does this ancestor already is indeterminate status
-                        if (
-                            current_styles[bg_prop].get("contrast_analysis")
-                            == "indeterminate"
-                        ):
-                            return {
-                                "value": None,
-                                "source_element": current,
-                                "contrast_analysis": "indeterminate",
-                                "reason": "ancestor_has_background_image",
-                                "original_background": current_styles[
-                                    bg_prop
-                                ].get("original_background", bg_value),
-                            }
-
-                        # Skip None values and continue searching
-                        if bg_value is None:
-                            continue  # Continue to next property
-
-                        # Check if this background contains a raster image
-                        if contains_raster_image(bg_value):
-                            return {
-                                "value": None,
-                                "source_element": current,
-                                "contrast_analysis": "indeterminate",
-                                "reason": "ancestor_has_background_image",
-                                "original_background": bg_value,
-                            }
-
-                        # Found explicit background
-                        bg_items = current_styles[bg_prop].items()
-                        return {
-                            "value": bg_value,
-                            "source_element": current,
-                            "contrast_analysis": "determinable",
-                            # Copy metadata from ancestor
-                            **{
-                                metadata_key: metadata_value
-                                for metadata_key, metadata_value in bg_items
-                                if metadata_key not in ["value"]
-                            },
-                        }
-
-            # If we flagged this ancestor to skip, move to next ancestor
-            if skip_ancestor:
-                current = current.parent
-                continue  # ✅ Now this continues to next ancestor
-
-        current = current.parent
-
-    # No ancestor background found, use default
-    return {
-        "value": DEFAULT_GLOBAL_BACKGROUND,
-        "source_element": None,
-        "contrast_analysis": "determinable",
-        "source": "default",
-    }
-
-
 def is_inheritable_property(property_name: str) -> bool:
     """
     Determines if a CSS property is inheritable by default.
@@ -1650,9 +1345,11 @@ def extract_property_source(property_data: dict) -> dict:
             "source_type": "visual_inheritance",
             "css_file": "visual_cascade",
             "selector": "ancestor_background",
-            "inherited_from": getattr(inherited_element, "name", None)
-            if inherited_element
-            else None,
+            "inherited_from": (
+                getattr(inherited_element, "name", None)
+                if inherited_element
+                else None
+            ),
         }
     elif source_type == "rule":
         return {

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/css_tools.py

@@ -2,6 +2,7 @@
 This module is a set of tools to analyze CSS syntax as well as properties
 and values.
 """
+
 import re
 from typing import Union
 
@@ -1234,7 +1235,7 @@ def get_colors_from_gradient(gradient: str) -> list:
     return colors
 
 
-def get_comment_positions(code: (str)) -> Union[list, None]:
+def get_comment_positions(code: str) -> Union[list, None]:
     """looks for index positions of first opening and closing comment.
 
     From this function, you can create a slice of a comment from the
@@ -1361,6 +1362,8 @@ def get_font_families(sheet: Stylesheet) -> list:
             # always take the last family as it would be an override in CSS
             family = families[-1]
             font_families.append({"selector": selector, "family": family})
+        else:
+            print()
     return font_families
 
 

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/font_tools.py

@@ -21,11 +21,15 @@ I will also not support calculating `ch` or `ex` since those are
 dependent upon the font-family itself and require information from the
 font-file or some other hidden calculation from the browser.
 """
+
 import re
 from typing import Any
 from typing import Union
+from file_clerk import clerk
 
 from webcode_tk import css_tools
+from webcode_tk import html_tools as html
+
 
 absolute_keyword_regex = (
     r"\b(?:xx-small|x-small|small(?!-caps)|medium|large|x-large|"
@@ -356,6 +360,103 @@ def is_valid_shorthand(value: str) -> bool:
     return is_valid
 
 
+def get_google_font_report(project_dir: str, min=1, max=2) -> str:
+    """determines if the page is using the min number of google fonts
+
+    We're looking for three things in each web page:
+    1) a link in the head to the googlefonts API,
+    2) each of those fonts being applied, and
+    3) at least the minimum number of unique Google fonts and no more than the
+       max #.
+
+    Args:
+        project_dir: the folder where the files reside
+        min: minimum number of Google font families in use
+        max: maximum number of Google font families in use
+
+    Returns:
+        report: a pass/fail report with accompanying data
+    """
+
+    # Loop through all HTML docs and their styles
+    report = []
+    styles = css_tools.get_styles_by_html_files(project_dir)
+    for data in styles:
+
+        # Step 1: get all linked Google fonts
+        file = data.get("file")
+        filename = clerk.get_file_name(file)
+        links = html.get_elements("link", file)
+        google_fonts_linked = []
+
+        for link in links:
+            href = link.attrs.get("href")
+            if (
+                "fonts.googleapis.com" in href
+                and href != "https://fonts.googleapis.com"
+            ):
+                fonts = get_google_font_data(href)
+                if isinstance(fonts, list):
+                    google_fonts_linked += fonts
+                else:
+                    google_fonts_linked.append(fonts)
+
+        # Check to see the linked fonts match required number.
+        num_fonts = len(google_fonts_linked)
+        if num_fonts < min:
+            data = f"fail: {filename} does not link to min number of Google "
+            data += "fonts."
+            report.append(data)
+            continue
+
+        # if we have any google fonts, are they being used?
+        stylesheets = data.get("stylesheets")
+        fonts_used = []
+        for sheet in stylesheets:
+            families = []
+            font_data = css_tools.get_font_families(sheet)
+            if font_data:
+                families = extract_families(font_data)
+            if families:
+                for family in google_fonts_linked:
+                    if family in families:
+                        if family not in fonts_used:
+                            fonts_used.append(family)
+
+        num_used = len(fonts_used)
+        if num_used >= min and num_used <= max:
+            data = f"pass: {filename} uses the correct number of Google fonts"
+            report.append(data)
+        else:
+            data = f"fail: {filename} with {num_used} font families does not "
+            data += "have enough applied Google fonts"
+            report.append(data)
+    return report
+
+
+def extract_families(family_data: list) -> list:
+    families = []
+    for datum in family_data:
+        family_value = datum.get("family")
+        family = family_value.split(",")[0]
+        family = family.strip()
+        family = family.replace('"', "")
+        family = family.replace("'", "")
+        families.append(family)
+    return families
+
+
+def get_google_font_data(href: str) -> list:
+    font_families = []
+    font_data = href.split("family=")
+    font_data.pop(0)
+    for item in font_data:
+        family = item.split(":")[0]
+        family = family.replace("+", " ")
+        font_families.append(family)
+    return font_families
+
+
 if __name__ == "__main__":
     sample_styles = """
 /* <absolute-size> values */

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/html_tools.py

@@ -12,6 +12,7 @@ elements were present or not.
     Typical usage example:
     ``
 """
+
 import os
 import re
 from typing import Union

{webcode_tk-1.2.12 → webcode_tk-1.2.18}/webcode_tk/ux_tools.py

@@ -15,6 +15,7 @@ According to the article...
     blocks of text
     - Use hypertext to split up long information into multiple pages"
 """
+
 import re
 from collections.abc import Sequence
 from typing import Union