webcode-tk 0.7.11__tar.gz → 1.0.4__tar.gz

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: webcode-tk
-Version: 0.7.11
+Version: 1.0.4
 Summary: 
 Home-page: https://github.com/HundredVisionsGuy/webcode-tk
 License: MIT
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: MechanicalSoup (>=1.1.0,<2.0.0)
 Requires-Dist: bs4 (>=0.0.1,<0.0.2)
 Requires-Dist: file-clerk (>=1.0.9,<2.0.0)

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "webcode-tk"
-version = "0.7.11"
+version = "1.0.4"
 description = ""
 authors = ["hundredvisionsguy <cwinikka@gmail.com>"]
 keywords = ["html", "validation", "css", ]

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/webcode_tk/__init__.py

@@ -18,4 +18,4 @@ Modules exported by this package:
 - `validator_tools`: sends HTML or CSS code to the W3C Validator to check
           for errors.
 """
-__version__ = "0.7.11"
+__version__ = "1.0.4"

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/webcode_tk/cascade_tools.py

@@ -5,12 +5,13 @@ inheritance and the cascade.
 The goal is to use the DOM, inheritance, and the cascade, to determine
 all styles applied to every element on the page.
 
-With that, it scans each stylesheet and applies eacSh style one at a time
+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
+from typing import Union
 
 from file_clerk import clerk
 
@@ -73,12 +74,14 @@ class Element(object):
         self.attributes = attributes
         self.background_color = {
             "value": "#ffffff",
+            "has_alpha": False,
+            "computed_value": "",
             "sheet": "user-agent",
             "selector": "",
             "specificity": "000",
             "applied_by": "context",
             "is_gradient": False,
-            "gradiparentent_colors": [],
+            "gradient_colors": [],
         }
         self.color = {
             "value": "#000000",
@@ -129,12 +132,14 @@ class Element(object):
             "normal_aaa": True,
             "normal_aa": True,
             "large_aaa": True,
+            "large_aa": True,
         }
         self.visited_contrast_data = {
             "ratio": 0.0,
             "normal_aaa": False,
             "normal_aa": False,
             "large_aaa": False,
+            "large_aa": False,
         }
         self.__set_link_color()
         self.get_contrast_data("default")
@@ -166,6 +171,7 @@ class Element(object):
         # get relevant specificity
         new_specificity = new_styles.get("specificity")
         col_specificity = self.color.get("specificity")
+
         # Check for overrides
         color_has_override = new_specificity >= col_specificity
 
@@ -263,7 +269,12 @@ class Element(object):
                 col, bg, self.ancestors
             )
             # Set bg to composite color with lowest contrast ratio
-            bg = results[0][-1]
+            bg = results[0][-2]
+            has_alpha = results[0][-1]
+            if has_alpha:
+                self.background_color["has_alpha"] = True
+                self.background_color["computed_value"] = bg
+
         hexc = color.get_hex(col)
         hexbg = color.get_hex(bg)
         self.__build_contrast_report(hexc, hexbg)
@@ -327,6 +338,9 @@ class Element(object):
         self.visited_contrast_data["large_aaa"] = bool(
             link_contrast.get("Large AAA") == "Pass"
         )
+        self.visited_contrast_data["large_aa"] = bool(
+            link_contrast.get("Large AA") == "Pass"
+        )
 
     def change_styles(
         self,
@@ -554,6 +568,7 @@ class Element(object):
         directly_targeted = self.directly_targets(selector)
         previously_set = self.background_color.get("applied_by") == "directly"
         bg_gradient = color.is_gradient(val)
+
         # If directly, check specificity
         if directly_targeted:
             if previously_set:
@@ -562,13 +577,49 @@ class Element(object):
             colors = []
             if bg_gradient:
                 self.background_color["is_gradient"] = True
+                c = self.color.get("value")
+                details = color.get_color_contrast_with_gradients(
+                    c, val, self.ancestors
+                )
                 colors = color.get_gradient_colors(val)
+
+                # Set gradient colors with highest and lowest contrast
+                self.background_color["best_contrast"] = {}
+                self.background_color["worst_contrast"] = {}
+
+                def process_gradient_data(details, bg_dict):
+                    contrast_ratio = details[0]
+                    size = self.font_size
+                    is_bold = self.is_bold
+                    results = color.get_contrast_results_from_ratio(
+                        contrast_ratio, size, is_bold
+                    )
+                    has_alpha = details[-1]
+                    if has_alpha:
+                        bg_dict["has_alpha"] = has_alpha
+                        self.background_color["has_alpha"] = True
+                        self.background_color["computed_value"] = details[3]
+                        bg_dict["computed_value"] = details[-2]
+                    else:
+                        bg_dict["value"] = details[2]
+                    bg_dict["contrast_ratio"] = details[0]
+                    bg_dict["results"] = results
+
+                best = details[-1]
+                worst = details[0]
+                process_gradient_data(
+                    best, self.background_color["best_contrast"]
+                )
+                process_gradient_data(
+                    worst, self.background_color["worst_contrast"]
+                )
                 self.background_color["gradient_colors"] = colors
             # set color, specificity, and directly applied
             self.background_color["value"] = val
             self.background_color["sheet"] = filename
             self.background_color["specificity"] = new_specificity
             self.background_color["applied_by"] = "directly"
+            self.background_color["selector"] = selector
         else:
             if not previously_set:
                 self.background_color["value"] = val
@@ -1441,6 +1492,94 @@ def update_contrast_results(
     return results
 
 
+def get_color_contrast_details(tree: CSSAppliedTree, rating="AAA") -> list:
+    """returns a list of all failures or a pass based on rating
+
+    We'll create a recursive inner nested function to traverse the DOM. We will
+    target only the styles that are applied directly so as to not overwhelm the
+    user and allow fixing the error more easily.
+
+    Args:
+        tree: the cascade tree for a single file.
+        rating: the rating of contrast we check for (AAA or AA). The default
+            is AAA.
+    Returns:
+        results"""
+    results = []
+    filename = tree.filename
+    # Loop recursively through the tree
+    elements = tree.children
+
+    def check_element(
+        el: Element, rating: str, filename: str
+    ) -> Union[list, None]:
+        children = el.children
+        msg = ""
+        applied_directly = (
+            el.background_color.get("applied_by") == "directly"
+            or el.color.get("applied_by") == "directly"
+        )
+        if applied_directly or el.name == "body":
+            is_gradient = el.background_color.get("is_gradient")
+            if is_gradient:
+                # get worst case
+                worst_case = el.background_color.get("worst_contrast")
+                worst_results = worst_case.get("results")
+                fails = "fail" in worst_results[:5]
+                if fails:
+                    selector = el.background_color.get("selector")
+                    if el.is_large:
+                        size = "Large"
+                    else:
+                        size = "Normal"
+                    msg = f"{el.name} tag (selector: {selector}) fails color "
+                    msg += f"contrast at {size} {rating}."
+                    results.append(msg)
+                    return
+            contrast_data = el.contrast_data
+            if el.is_large:
+                if rating == "AAA":
+                    passes = contrast_data.get("large_aaa")
+                else:
+                    passes = contrast_data.get("large_aa")
+            else:
+                if rating == "AAA":
+                    passes = contrast_data.get("normal_aaa")
+                else:
+                    passes = contrast_data.get("normal_aa")
+            # only add results if failure
+            if not passes:
+                if el.is_large:
+                    size = "Large"
+                else:
+                    size = "Normal"
+                selector = el.background_color.get("selector")
+                if not selector:
+                    selector = el.color.get("selector")
+                msg = f"{el.name} tag (selector: {selector}) fails color "
+                msg += f"contrast at {size} {rating}."
+                results.append(msg)
+        if not children:
+            return
+        else:
+            for kid in children:
+                check_element(kid, rating, filename)
+
+    for element in elements:
+        check_element(element, rating, filename)
+    if results:
+        adjusted = []
+        for result in results:
+            adjusted.append("fail: " + result)
+        results = adjusted
+    else:
+        # It's a success! Let's let them know
+        msg = f"success: {filename} passes color contrast for {rating} Normal"
+        msg += " and Large."
+        results.append(msg)
+    return results
+
+
 if __name__ == "__main__":
     project_path = "tests/test_files/attribute_selector_file"
     project_path = "tests/test_files/large_project/"
@@ -1453,6 +1592,7 @@ if __name__ == "__main__":
             sheet,
         ],
     )
+    results = get_color_contrast_details(gradient_tree, "AAA")
     styles_by_html_files = css.get_styles_by_html_files(project_path)
     for file in styles_by_html_files:
         filepath = file.get("file")
@@ -1461,4 +1601,3 @@ if __name__ == "__main__":
         results = {}
         root = css_tree.children[0]
         results = get_color_contrast_results(root, results)
-        print(results)

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/webcode_tk/color_tools.py

@@ -78,6 +78,44 @@ def passes_color_contrast(level: str, hex1: str, hex2: str) -> bool:
     return passes
 
 
+def get_contrast_results_from_ratio(
+    ratio: float, size: float, is_bold: bool
+) -> str:
+    """takes contrast, compares to map and returns results as a string
+
+    Args:
+        ratio: the contrast ratio.
+        size: calculated font size.
+
+    Returns:
+        str: whether it passes or not with details.
+    """
+    # is the text large or not?
+    is_large = size >= 24 or is_bold and size >= 16.66
+    if is_large:
+        aaa_goal = contrast_ratio_map.get("Large AAA")
+        passes = ratio >= aaa_goal
+        if passes:
+            return "pass: Large AAA contrast rating"
+        aa_goal = contrast_ratio_map.get("Large AA")
+        conditionally_passes = ratio >= aa_goal
+        if conditionally_passes:
+            return "conditional pass: Large AA contrast rating"
+        else:
+            return "fail: fails all contrast ratings"
+    else:
+        aaa_goal = contrast_ratio_map.get("Normal AAA")
+        passes = ratio >= aaa_goal
+        if passes:
+            return "pass: Normal AAA contrast rating"
+        aa_goal = contrast_ratio_map.get("Normal AA")
+        conditionally_passes = ratio >= aa_goal
+        if conditionally_passes:
+            return "conditional pass: Normal AA contrast rating"
+        else:
+            return "fail: fails normal sized text contrast"
+
+
 def get_color_contrast_report(hex1: str, hex2: str) -> dict:
     """creates a report on how the two hex colors rate on the color
     contrast chart
@@ -794,10 +832,18 @@ def get_color_contrast_with_gradients(
             # append to results list
             if composite_color:
                 results.append(
-                    (contrast, foreground, background, composite_color)
+                    (
+                        contrast,
+                        foreground,
+                        background,
+                        composite_color,
+                        bg_has_alpha,
+                    )
                 )
             else:
-                results.append((contrast, foreground, background, background))
+                results.append(
+                    (contrast, foreground, background, background, False)
+                )
     results.sort()
     return results
 

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/webcode_tk/css_tools.py

@@ -2222,6 +2222,260 @@ def is_link_selector(selector: str) -> bool:
     return bool(selector_match)
 
 
+def get_all_project_stylesheets(project_dir: str) -> list:
+    """returns a list of all styles and stylesheets from a project folder.
+
+    This includes styles from style tags as well as linked stylesheets.
+
+    Args:
+        project_dir: the relative link to the folder with the web docs.
+
+    Returns:
+        all_files_styles: a list of all stylesheets and style tag contents.
+    """
+    directory = project_dir
+    html_files = clerk.get_all_files_of_type(directory, "html")
+    all_files_styles = []
+    for file in html_files:
+        filename = clerk.get_file_name(file)
+        stylesheets = get_all_stylesheets_by_file(file)
+        all_files_styles.append((filename, stylesheets))
+    return all_files_styles
+
+
+def no_style_attributes_allowed_report(project_dir: str) -> list:
+    """returns a report on whether HTML docs use style attributes or not.
+
+    Only call this report if you do not allow a style attribute in an
+    HTML doc
+
+    Args:
+        project_dir: the relative link to the folder with the web docs.
+
+    Returns:
+        report: a list of all HTML docs and a pass or fail message.
+    """
+    report = []
+
+    html_files = clerk.get_all_files_of_type(project_dir, "html")
+    for file in html_files:
+        try:
+            has_style_attr = html_tools.has_style_attribute_data(file)
+        except AttributeError:
+            continue
+        if has_style_attr:
+            result = f"fail: {file} uses style attributes"
+        else:
+            result = f"pass: {file} does not use style attributes"
+        report.append(result)
+    return report
+
+
+def styles_applied_report(project_dir: str) -> list:
+    """returns a report of all files in a project folder that apply styles
+
+    This lets us know for each HTML doc if they apply styles (pass) or
+    if they do not apply styles (fail)
+
+    Args:
+        project_dir: a relative path to the project folder.
+
+    Returns:
+        report: a list of HTML docs and whether they pass or fail (pass) means
+            they did apply styles and fail is the opposite.
+    """
+    report = []
+    html_files = clerk.get_all_files_of_type(project_dir, "html")
+    for file in html_files:
+        styles = get_all_stylesheets_by_file(file)
+        if not styles:
+            results = f"fail: {file} does NOT apply CSS."
+        else:
+            results = f"pass: {file} applies CSS."
+        report.append(results)
+    return report
+
+
+def fonts_applied_report(project_dir: str, min=1, max=2) -> list:
+    """returns a report of all files in a project folder that apply font
+    families.
+
+    You can set the minimum and maximum number of fonts applied per page.
+
+    Args:
+        project_dir: the relative path to the project folder we want to check.
+        min: the minimum number of fonts applied per file.
+        max: the maximum number of fonts applied per file.
+    Returns:
+        report: a list of font data results.
+    """
+    report = []
+    all_file_data = get_styles_by_html_files(project_dir)
+    for file in all_file_data:
+        font_families_applied = []
+        number_of_fonts = 0
+        filename = clerk.get_file_name(file.get("file"))
+        stylesheets = file.get("stylesheets")
+        for sheet in stylesheets:
+            font_details = get_font_families(sheet)
+            number_of_fonts += len(font_details)
+            for item in font_details:
+                results = None
+                selector = item.get("selector")
+                family = item.get("family")
+                if "," in family:
+                    first_font = family.split(",")[0].strip()
+                else:
+                    first_font = family
+                first_font = first_font.replace("'", "")
+                first_font = first_font.replace('"', "")
+                if first_font not in font_families_applied:
+                    font_families_applied.append(first_font)
+                if first_font.lower() == "times new roman":
+                    results = f"fail: {filename}: {selector} element was set "
+                    results += "to the default font"
+        num_fonts = len(font_families_applied)
+        if num_fonts >= min and num_fonts <= max:
+            results = f"pass: {filename} applied {num_fonts} "
+            if num_fonts == 1:
+                current_font = font_families_applied[0]
+                results += f"font: {current_font}"
+            else:
+                results += "fonts:"
+                for i in range(num_fonts):
+                    current_font = font_families_applied[i]
+                    if current_font == font_families_applied[-1]:
+                        results += f"and {current_font}"
+                    elif num_fonts > 2:
+                        results += f" {current_font}, "
+                    else:
+                        results += f" {current_font} "
+            results += "."
+        elif num_fonts < min:
+            results = f"fail: {filename} did not apply {min} fonts, "
+            results += f"instead, it applied {num_fonts} fonts."
+        elif num_fonts > max:
+            results = f"fail: {filename} applied too many fonts; "
+            results += f" it applied {num_fonts} fonts."
+        if results and results not in report:
+            report.append(results)
+    if not report:
+        report.append("fail: no html files to apply font styling to")
+    return report
+
+
+def get_global_color_report(project_dir: str, level="aaa") -> list:
+    """Returns a report on which files in a project apply global colors
+
+    Args:
+        project_dir: the project folder path.
+        level: whether we are testing for Normal AAA or Normal AA
+
+    Returns:
+        report: a list of files and a pass or fail message for each."""
+    report = []
+    all_file_data = get_all_project_stylesheets(project_dir)
+    for data in all_file_data:
+        filename = data[0]
+        passes = []
+        for sheet in data[1]:
+            rules = sheet.rulesets
+            global_color_data = get_global_color_details(rules)
+            if global_color_data:
+                for item in global_color_data:
+                    file, result = get_color_data(filename, item, level)
+                    passes.append(f"pass: {file} {result}")
+        if passes:
+            details = ""
+            for detail in passes:
+                details += detail
+        else:
+            details = f"fail: {filename} does NOT apply global colors"
+        report.append(details)
+    if not report:
+        report.append("fail: no html files to apply color styles to")
+    return report
+
+
+def get_color_data(file: str, color_details: dict, level="aaa") -> tuple:
+    """returns the color contrast data on a color.
+
+    pulls out the selector, background color, text color, contrast
+    ratio, and whether it passes color contrast.
+
+    Args:
+        file: just the name of the file (not path).
+        color_details: tuple of full color & bg color details.
+        level: the level of normal text (AAA or AA).
+
+    Returns:
+        color_data: a tuple with filename and results as a string"""
+    selector = color_details.get("selector")
+    bg_color = color_details.get("background-color")
+    color = color_details.get("color")
+    contrast_ratio = color_details.get("contrast_ratio")
+    if level == "aaa":
+        passes = color_details.get("passes_normal_aaa")
+    else:
+        passes = color_details.get("passes_normal_aa")
+    if passes:
+        results = "passes global colors"
+    else:
+        results = f"{selector} {bg_color} and {color} fail with a contrast"
+        results += f" ratio of {contrast_ratio}."
+    color_data = (file, results)
+    return color_data
+
+
+def get_heading_color_report(project_dir: str) -> list:
+    """Returns a report on which files in a project apply heading colors
+
+    For now, we just want to have at least a color or background color
+    applied.
+
+    Args:
+        project_dir: the project folder path.
+
+    Returns:
+        report: a list of files and a pass or fail message for each."""
+    report = []
+    header_re = regex_patterns.get("header_selector")
+    if project_dir[-1] != "/":
+        project_dir += "/"
+    all_file_data = get_all_project_stylesheets(project_dir)
+    for file in all_file_data:
+        filename = file[0]
+        filepath = project_dir + filename
+        all_color_rules = get_all_color_rules(filepath)
+        header_selectors = []
+        for key, val in all_color_rules.items():
+            if key == "file":
+                continue
+            is_header_selector = re.findall(header_re, key)
+            if is_header_selector:
+                # we have a header selector
+                # we only need to check color
+                color_data = val
+                color_value = color_data.get("color")
+                bg_value = color_data.get("background-color")
+                if color_value:
+                    if bg_value:
+                        header_selectors.append(
+                            (filename, color_value, bg_value)
+                        )
+                    else:
+                        header_selectors.append((filename, color_value, None))
+                if bg_value:
+                    header_selectors.append((filename, None, bg_value))
+        if header_selectors:
+            report.append(f"pass: {filename} applies colors to headers")
+        else:
+            report.append(f"fail: {filename} does NOT apply colors to headers")
+    if not report:
+        report.append("fail: no html files to apply header colors to")
+    return report
+
+
 if __name__ == "__main__":
     insane_gradient = """
     -moz-radial-gradient(0% 200%, ellipse cover,

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/webcode_tk/html_tools.py

@@ -410,6 +410,30 @@ def add_if_not_in(my_list: list, item: str) -> None:
         my_list.append(item)
 
 
+def get_number_of_elements_per_file(
+    project_dir: str, element_data: list
+) -> list:
+    """returns a list of number of elements per file in a project folder.
+
+    Args:
+        project_dir: the folder we want to check
+        element_data: a list of tuples of element (str) and required number
+        (int)
+
+    Returns:
+        elements_per_file: a list of tuples that includes the file, the
+            element, and the number of occurrences.
+    """
+    elements_per_file = []
+    all_html_files = get_all_html_files(project_dir)
+    for file in all_html_files:
+        for i in range(len(element_data)):
+            # Get requirements for exact number
+            element, number = element_data[i]
+            elements_per_file.append((file, element, number))
+    return elements_per_file
+
+
 if __name__ == "__main__":
     file_with_inline_styles = "tests/test_files/sample_with_inline_styles.html"
     markup = clerk.file_to_string(file_with_inline_styles)

{webcode_tk-0.7.11 → webcode_tk-1.0.4}/webcode_tk/validator_tools.py

@@ -7,6 +7,8 @@ import requests
 from bs4 import BeautifulSoup
 from file_clerk import clerk
 
+from webcode_tk import html_tools as html
+
 w3cURL = "https://validator.w3.org/nu/?out=json"
 
 # Instantiate a stateful browser
@@ -89,7 +91,7 @@ def get_markup_validity(file_path: str) -> list:
         errors: a list of dictionary types (converted from the JSON
             response from the validator."""
     errors = []
-    payload = open(file_path)
+    # payload = open(file_path)
     with open(file_path, "rb") as payload:
         headers = {
             "content-type": "text/html; charset=utf-8",
@@ -253,6 +255,61 @@ def validate_css(css_code: str) -> bs4.ResultSet:
     return results
 
 
+def get_project_validation(project_dir: str, type="html") -> list:
+    """returns a report on HTML or CSS validation per HTML file.
+
+    You choose the project folder and the type (html or css), and it
+    will return a list of per-files errors
+    """
+    report = []
+    passing_files = []
+    all_files = clerk.get_all_project_files(project_dir)
+    for file in all_files:
+        errors = []
+        file_type = clerk.get_file_type(file)
+        filename = clerk.get_file_name(file)
+        if type == "html" and file_type == "html":
+            errors = get_markup_validity(file)
+            if errors:
+                report.append(
+                    f"fail: {filename} has {len(errors)} validation errors."
+                )
+            else:
+                passing_files.append(filename)
+        else:
+            if file_type == "html" and type == "css":
+                style_tag = html.get_elements("style", file)
+                if style_tag:
+                    code = html.get_element_content(style_tag)
+                    result = validate_css(code)
+                    errors_list = get_css_errors_list(result)
+                    if errors_list:
+                        errors += errors_list
+                    else:
+                        passing_files.append(filename)
+            if file_type == "css":
+                code = clerk.file_to_string(file)
+                result = validate_css(code)
+                errors_list = get_css_errors_list(result)
+                if errors_list:
+                    errors += errors_list
+                else:
+                    passing_files.append(filename)
+            if errors:
+                report.append(
+                    f"fail: {filename} has {len(errors)} css errors."
+                )
+    if not report:
+        if passing_files:
+            for passing_file in passing_files:
+                msg = f"pass: {passing_file} passes {type.upper()} validation"
+                report.append(msg)
+        if not passing_files:
+            report.append("fail: no files present to validate")
+    # TODO - make sure this covers all scenarios
+    return report
+
+
 if __name__ == "__main__":
     path = "tests/test_files/sample_with_errors.html"
     report = get_markup_validity(path)