rephorm 1.0.1__py3-none-any.whl

rephorm/utility/fonts/font_loading.py

@@ -0,0 +1,74 @@
+import os
+import sys
+from logging import warning
+
+
+def get_fonts(load_fonts):
+
+    default_fonts = get_default_fonts()
+
+    if not load_fonts:
+        return default_fonts
+
+    font_map = {(font['font_path']): font for font in default_fonts}
+
+    # Update or append additional fonts
+    for font in load_fonts:
+        key = (font['font_path'])
+        font_map[key] = font
+
+    return list(font_map.values())
+
+def get_default_fonts():
+    base_path = os.path.abspath(os.path.dirname(__file__))
+    return [
+        {
+         "font_family": "Open Sans",
+         "font_path": os.path.join(base_path, "OpenSans.ttf"),
+         "font_style": ""},
+        {
+         "font_family": "Open Sans",
+         "font_path": os.path.join(base_path, "OpenSans-Italic.ttf"),
+         "font_style": "I"},
+        {
+         "font_family": "Open Sans",
+         "font_path": os.path.join(base_path, "OpenSans-Bold.ttf"),
+         "font_style": "B"},
+        {
+         "font_family": "Open Sans",
+         "font_path": os.path.join(base_path, "OpenSans-BoldItalic.ttf"),
+         "font_style": "BI"},
+    ]
+
+def validate_fonts(fonts):
+
+    required_styles = {"", "I", "B"}
+
+    grouped_fonts = {}
+    for font in fonts:
+        family = font["font_family"]
+        style = font["font_style"].upper()
+        if family not in grouped_fonts:
+            grouped_fonts[family] = set()
+        grouped_fonts[family].add(style)
+
+    for font_family, available_styles in grouped_fonts.items():
+        missing_styles = required_styles - available_styles
+        if missing_styles:
+            raise Exception(f"Font family '{font_family}' is missing styles: {', '.join(missing_styles)}")
+
+
+def add_custom_fonts(pdf, fonts):
+
+    if fonts is not None:
+        try:
+            validate_fonts(fonts)
+        except Exception as e:
+            warning(e)
+            sys.exit(1)
+
+            # Font loading
+    for font_dict in fonts:
+        pdf.add_font(family = font_dict.get("font_family"),
+                     fname=font_dict.get('font_path'),
+                     style=font_dict.get('font_style', ''))

rephorm/utility/is_set.py

@@ -0,0 +1,9 @@
+"""
+Function that checks whether all provided arguments are non-falsy.
+
+Example:
+    is_set(param_x, param_y)
+    This will return True if BOTH params are truthy (not None, False, 0, '').
+"""
+def is_set(*args):
+    return all(arg is not None for arg in args)

rephorm/utility/merge/chart_properties_manager.py

@@ -0,0 +1,80 @@
+import copy
+
+from rephorm.dict.styles import default_styles
+
+class ChartPropertiesManager:
+    def __init__(self):
+        self.init_properties()
+
+    def init_properties(self):
+
+        # actually we don't need default here bcs it takes from styles in merge_settings anyway.
+        self.default_bar_colors = default_styles()["chart"]["bar_color_order"]
+        self.default_line_colors = default_styles()["chart"]["line_color_order"]
+        self.default_line_styles = default_styles()["chart"]["line_styles_order"]
+        self.default_line_widths = default_styles()["chart"]["line_width_order"]
+        # set memory
+        self.bar_colors = copy.deepcopy(self.default_bar_colors)
+        self.line_widths = copy.deepcopy(self.default_line_widths)
+        self.line_colors = copy.deepcopy(self.default_line_colors)
+        self.line_styles = copy.deepcopy(self.default_line_styles)
+
+        # set working stack
+        self.bar_color_stack = copy.deepcopy(self.bar_colors)
+        self.line_widths_stack = copy.deepcopy(self.line_widths)
+        self.line_color_stack = copy.deepcopy(self.line_colors)
+        self.line_style_stack = copy.deepcopy(self.line_styles)
+
+    def get_bar_color(self):
+        if not self.bar_color_stack:
+            self.bar_color_stack = copy.deepcopy(self.bar_colors)
+        return self.bar_color_stack.pop(0)
+
+    def get_line_width(self):
+        if not self.line_widths_stack:
+            self.line_widths_stack = copy.deepcopy(self.line_widths)
+        return self.line_widths_stack.pop(0)
+
+    def get_line_color(self):
+        if not self.line_color_stack:
+            self.line_color_stack = copy.deepcopy(self.line_colors)
+        return self.line_color_stack.pop(0)
+
+    def get_line_style(self):
+        if not self.line_style_stack:
+            self.line_style_stack = copy.deepcopy(self.line_styles)
+        return self.line_style_stack.pop(0)
+
+    def update_colors_for_chart(self, bar_colors=None, line_colors=None, line_styles=None, line_widths=None):
+
+        self.bar_color_stack.clear()
+        self.line_color_stack.clear()
+        self.line_style_stack.clear()
+        self.line_widths_stack.clear()
+
+        self.bar_colors = bar_colors if bar_colors and bar_colors is not None else copy.deepcopy(self.default_bar_colors)
+        self.line_colors = line_colors if line_colors and line_colors is not None else copy.deepcopy(self.default_line_colors)
+        self.line_styles = line_styles if line_styles and line_styles is not None else copy.deepcopy(self.default_line_styles)
+        self.line_widths = line_widths if line_widths and line_widths is not None else copy.deepcopy(self.default_line_widths)
+
+        self.bar_color_stack = copy.deepcopy(self.bar_colors)
+        self.line_color_stack = copy.deepcopy(self.line_colors)
+        self.line_style_stack = copy.deepcopy(self.line_styles)
+
+chart_properties = ChartPropertiesManager()
+
+def get_bar_color():
+    return chart_properties.get_bar_color()
+
+def get_line_width():
+    return chart_properties.get_line_width()
+
+def get_line_color():
+    return chart_properties.get_line_color()
+
+
+def get_line_style():
+    return chart_properties.get_line_style()
+
+def update_chart_properties(bar_colors=None, line_colors=None, line_styles=None, line_widths=None):
+    return chart_properties.update_colors_for_chart(bar_colors, line_colors, line_styles, line_widths)

rephorm/utility/merge/merge_settings.py

@@ -0,0 +1,134 @@
+import copy
+
+from rephorm.dict.styles import default_styles, DEFAULT_FONT_FAMILY
+from rephorm.object_params.settings import object_params
+from rephorm.utility.merge.chart_properties_manager import get_bar_color, get_line_color, \
+    get_line_style, update_chart_properties, get_line_width
+from rephorm.utility.merge.merge_styles import update_nested_structure, create_nested_structure
+
+
+def merge_settings(obj, params):
+    """
+    obj - The current object (e.g., Report, Chapter, etc.)
+    params - A dictionary of parameters to propagate | That is report. settings
+    """
+    #Todo: Known issue: if you set report.font_size on level of chart,
+    # it will not recalculate font sizes for chart and it's children.
+    # ...
+    # This is because at that point of iteration there is local params dictionary,
+    # and we update it with what comes from children. To update reference
+    # font format when children gets report.font_size parameter (reference parameters)
+    # we would need to reinitialize default dict with those values from the children,
+    # but we cant do it because we would loose the state of the local params,
+    # which already have some important settings preset for us.
+    # ...
+
+    local_params = copy.deepcopy(params)
+
+    parent_styles = create_nested_structure(obj.__class__.__name__, local_params.get("styles", {}))
+    parent_font_family = parent_styles.get("report", {}).get("font_family", DEFAULT_FONT_FAMILY)
+
+    object_styles = create_nested_structure(obj.__class__.__name__, obj.settings.__dict__.get("styles", {}))
+    obj_font_family = object_styles.get("font_family", parent_font_family)
+
+    # We update the default styles with styles coming from the previous parent (local_params["styles"]),
+    # preserving inherited values. This avoids overwriting/resetting them as before (line 40),
+    # where default_styles was directly assigned to local_params["styles"].
+
+    local_params["styles"] = update_nested_structure(
+        default_styles(obj_font_family),
+        create_nested_structure(obj.__class__.__name__,local_params.get("styles", {}))
+    )
+
+    for key in object_params.keys():
+        # Check if the key exists in params; if not, use its default value
+        parent_value = local_params.get(key, None)
+        # Check if obj.settings already has this key set
+        if hasattr(obj.settings, key) and getattr(obj.settings, key) is not None:
+            current_obj_value = getattr(obj.settings, key)
+
+            if key == "styles":
+                current_obj_value = update_nested_structure(parent_value, create_nested_structure(obj.__class__.__name__, current_obj_value))
+
+            setattr(obj.settings, key, current_obj_value)
+            local_params[key] = current_obj_value
+
+        elif parent_value is not None:
+            ultimate_owners = object_params.get(key, {}).get("ultimates", [])
+            if type(obj).__name__ in ultimate_owners:
+                setattr(obj.settings, key, parent_value)
+
+        # If no value is set yet, use the default from ultimate_setting_owner
+        elif getattr(obj.settings, key, None) is None:
+            ultimate_owners = object_params.get(key, {}).get("ultimates", [])
+            if type(obj).__name__ in ultimate_owners:
+                if key == "styles":
+                    setattr(obj.settings, key, getattr(local_params, key))
+                else:
+                    setattr(obj.settings, key, object_params[key].get("default_value", None))
+
+    if obj.__class__.__name__ == "Chart":
+        structured_styles = create_nested_structure(obj.__class__.__name__, obj.settings.styles) \
+            if hasattr(obj.settings, "styles") \
+            else {}
+        update_chart_properties(structured_styles.get("chart", {}).get("bar_color_order", None),
+                                structured_styles.get("chart", {}).get("line_color_order", None),
+                                structured_styles.get("chart", {}).get("line_styles_order", None),
+                                structured_styles.get("chart", {}).get("line_width_order", None),
+                                )
+
+    if hasattr(obj, "CHILDREN") and isinstance(obj.CHILDREN, list):
+        list_of_obj = [obj.CHILDREN[-1]] if obj.__class__.__name__ == "Report" and obj.CHILDREN else obj.CHILDREN
+        for child in list_of_obj:
+            if hasattr(child, "settings"):
+                merge_settings(child, local_params)
+                handle_object_properties(child, child.settings.styles)
+
+"""
+This function process final styles dictionary and assigns colors to chartSeries based on series type, using predefined color order.
+If the color is not user-defined, it assigns the next color from the global color order. (Non user defined colors coming as "None" by default)
+
+When we call this function we do not need to ensure that the necessary dict structure
+exists or that keys are present, because who calls this function should already have it set.
+This function should not be called on styles dict, that was not processed (missing keys/values)
+or that is not properly structured (dict that is flat / or not following the correct order)
+"""
+
+# TODO: Implement multivariate series support with consistent color assignment
+#  Current Issue:
+#  When creating a single series object that contains multiple data components (multivariate),
+#  the color assignment system only applies a single color to the entire series.
+#  Implementation:
+#  Here we would detect if the series that is coming are multivariate or single,
+#  basically check if single, assign color, else create an array for the length of
+#  data columns in the series, populate it with get_bar_color() until it's full,
+#  and pass it to styles as "bar_face_color"
+
+def handle_object_properties(obj, merged_styles):
+
+    if obj.__class__.__name__ == "ChartSeries":
+
+        is_multivariate = obj.data.num_variants > 1
+
+        series_type = getattr(obj.settings, "series_type")
+        series_styles = merged_styles["chart"]["series"]
+
+        def assign_style(key, generator_func):
+            if key not in series_styles or series_styles[key] is None:
+                if is_multivariate:
+                    series_styles[key] = [generator_func() for _ in range(obj.data.num_variants)]
+                else:
+                    series_styles[key] = generator_func()
+
+        if series_type in (
+            "bar", "contribution_bar", "barcon", "conbar", "bar_color_stack",
+            "bar_group", "bar_overlay", "bar_relative"
+        ):
+            assign_style("bar_face_color", get_bar_color)
+        else:
+            assign_style("line_color", get_line_color)
+            assign_style("line_style", get_line_style)
+            # line width: typically same for all?
+            assign_style("line_width", get_line_width)
+
+

rephorm/utility/merge/merge_styles.py

@@ -0,0 +1,79 @@
+import copy
+
+from rephorm.dict.styles import default_styles
+
+# Get the allowed Styles structure from default_styles
+allowed_structure = default_styles()
+
+def validate_value_type(obj_name, path, value, structure=allowed_structure):
+    keys = path.split('.')
+    final_structure = structure
+    current_path = []
+
+    for key in keys:
+        current_path.append(key)
+        if isinstance(final_structure, dict):
+            if key not in final_structure:
+                raise KeyError(f"({obj_name} object): Styles key '{key}' for '{'.'.join(current_path[:-1])}' does not exist. "
+                               f"Available keys at this level: {list(final_structure.keys())}")
+            final_structure = final_structure.get(key, {})
+        else:
+            # If we've reached a non-dictionary node, we can't go further; this means wrong nesting
+            raise KeyError(f"Styles: Invalid path '{path}'. No further nesting allowed under '{keys[-2]}'.")
+
+    if isinstance(final_structure, dict):
+        if not isinstance(value, dict):
+            available_keys = list(final_structure.keys())
+            raise ValueError(
+                f"Styles key error: '{path}' expects a dictionary with keys: {available_keys}. Got {type(value).__name__} instead.")
+        else:
+            # Recursively validate each sub-key for dictionaries
+            for sub_key, sub_value in value.items():
+                new_path = f"{path}.{sub_key}"
+                validate_value_type(obj_name, new_path, sub_value)
+    else:
+        # Skips type validation if the type of Final structure's (edge parameter in default_styles)
+        # value was set to None.
+        if type(final_structure) is type(None):
+            return
+
+        expected_type = type(final_structure) if not isinstance(final_structure, type) else final_structure
+
+        if not isinstance(value, expected_type) and not (isinstance(value, (int, float)) and expected_type in (int, float)):
+            raise TypeError(
+                f"Styles: Invalid type for '{path}': Expected {expected_type.__name__}, got {type(value).__name__}")
+
+def create_nested_structure(obj_name, flat_dict):
+
+    if flat_dict is None:
+        return flat_dict
+
+    nested_dict = {}
+
+    flat_dict = copy.deepcopy(flat_dict)
+
+    for key, value in flat_dict.items():
+        validate_value_type(obj_name, key, value, allowed_structure)
+        keys = key.split(".")
+        d = nested_dict
+
+        for k in keys[:-1]:
+            d = d.setdefault(k, {})
+
+        d[keys[-1]] = value
+
+    return nested_dict
+
+def update_nested_structure(org_dict, new_dict):
+    if new_dict is None:
+        return org_dict
+
+    result = copy.deepcopy(org_dict)
+
+    for key, value in new_dict.items():
+        if isinstance(value, dict) and key in result and isinstance(result[key], dict):
+            result[key] = update_nested_structure(result[key], value)
+        else:
+            result[key] = value
+
+    return result

rephorm/utility/merge/pdf_merger.py

@@ -0,0 +1,29 @@
+import fitz  # PyMuPDF
+
+# Takes units in PT (Therefore must be converted correctly)
+def overlay_pdfs(base_pdf_path, pdf_data, output_pdf_path):
+    base_pdf = fitz.open(base_pdf_path)
+
+    for pdf_info in pdf_data:
+        page_num = pdf_info['page']-1
+        overlay_pdf = fitz.open(pdf_info['pdf_path'])
+        base_page = base_pdf[page_num]
+
+        x = (pdf_info['x']) # X coordinate of the bottom-left corner of the overlay
+        y = (pdf_info['y']) # Y coordinate of the bottom-left corner of the overlay
+        width = (pdf_info['width'])  # Width of the overlay
+        height = (pdf_info['height'])  # Height of the overlay
+
+        # Define the position rectangle for the overlay
+        position = fitz.Rect(x, y, x + width, y + height)
+
+        # Draw a rectangle for visual debugging
+        # red_color = (1, 0, 0)
+        # base_page.draw_rect(position, color=red_color, width=1.5, fill=None)
+
+        # Place the overlay PDF
+        base_page.show_pdf_page(position, overlay_pdf, 0)
+        overlay_pdf.close()
+
+    base_pdf.save(output_pdf_path)
+    print(f"Overlay PDF saved: {output_pdf_path}")

rephorm/utility/report/add_footnotes.py

@@ -0,0 +1,46 @@
+from fpdf import enums
+
+# Todo add some space after line, between line and first footnote
+
+def add_footnotes_at_bottom(pdf, footnotes, reference_nr, last_y = None, **kwargs):
+
+    font_size = kwargs.get('font_size')
+    font_family = kwargs.get('font_family')
+    font_style = kwargs.get('font_style')
+    footer_padding = kwargs.get('footer_padding')
+    footer_top_margin = kwargs.get('footer_top_margin')
+
+
+    bottom_padding = 10
+    b_margin = pdf.b_margin
+
+    # prevent auto page break - this is a MUST!!!!!
+    # else it would push content and footnotes to new page if slightly overflows
+    pdf.set_auto_page_break(auto=False)
+
+    pdf.set_font(font_family, font_style, font_size)
+
+    #Sets line color above the footnotes
+    pdf.set_draw_color(0, 0, 0)
+
+    # current b_margin = page_margin_bottom + footer_height + footer_top_margin
+    footer_position = pdf.h - b_margin + footer_top_margin
+
+    if last_y is None:
+        footnote_y_position = pdf.h - b_margin + footer_padding + footer_top_margin
+        pdf.line(x1=pdf.l_margin, y1=footer_position, x2=pdf.w - pdf.r_margin, y2=footer_position)
+    else:
+        footnote_y_position = last_y
+
+    pdf.set_y(footnote_y_position)
+
+    for ref, footnote in zip(reference_nr, footnotes):
+        formatted_footnote = f"[{ref}] {footnote}"
+        pdf.multi_cell(w=pdf.w - pdf.l_margin - pdf.r_margin, h=None, text=formatted_footnote, align='L', new_x=enums.XPos.LEFT)
+        last_y = pdf.get_y() + bottom_padding
+
+    # Reset auto page break and b_margin
+    # Todo: drop footer height, rename footer padding to bottom_margin_padding, and footnotes pos y would be pdf.h - b.margin
+    pdf.set_auto_page_break(auto=True, margin = b_margin)
+
+    return last_y

rephorm/utility/report/cleanup_utility.py

@@ -0,0 +1,19 @@
+# make util funct cleanup later on, so less code regarding cleanup stuff. but call it here.
+import os
+import shutil
+
+from rephorm.object_mappers._globals import reset_figure_map
+
+def perform_cleanup(cleanup: bool = False, directory_path: str = None, base_file_path: str = None):
+
+    reset_figure_map()
+
+    try:
+        # Remove tmp dir where pdf figures are stored
+        if cleanup:
+            shutil.rmtree(directory_path)
+        # Remove base (initial) pdf
+        os.remove(base_file_path)
+
+    except Exception as e:
+        print(f"Cleanup utility - error occurred: {e}")

rephorm/utility/report/footnotes_counter.py

@@ -0,0 +1,15 @@
+from rephorm.utility.is_set import is_set
+footnote_counter = 0
+
+def generate_footnote_numbers(footnotes):
+    """
+    Generate list of numbers for the footnotes
+    Uses a global counter.
+    """
+    global footnote_counter
+    references = []
+    if is_set(footnotes):
+        for _ in footnotes:
+            footnote_counter += 1
+            references.append(str(footnote_counter))
+    return references

rephorm/utility/report/image_utility.py

@@ -0,0 +1,14 @@
+# Todo: Consider making part of ChartMapper method (that should be implemented from interface) | Rename to render_chart
+import plotly.io as pio
+pio.kaleido.scope.mathjax = None
+
+def to_image(series, image_format="pdf", width=None, height=None):
+    """
+    Converts a chart to an image in the specified format and dimensions.
+    """
+    try:
+        return series.to_image(format=image_format, width=width, height=height)
+
+    except Exception as e:
+        print(f"Error generating image from chart: {e}")
+        return None

rephorm/utility/report/layout_utility.py

@@ -0,0 +1,59 @@
+"""
+pdf.b_margin = b.margin + footer_height + footer_top_margin.
+"""
+class LayoutManager:
+    def __init__(self, pdf, used_top_height = 0):
+        """
+        Initialize the layout manager with pdf instance, and header and footer height.
+        """
+        self.pdf = pdf
+        self.used_top_height = used_top_height
+
+    def calculate_position(self, layout, nrow, ncol):
+        """
+        Here we compute grid layout based on user inputs and return array with every element X Y W H "coordinates"
+        Result - array with coordinates of each element and key is (row_indx, col_indx)
+        """
+        result={}
+
+        cell_width = ((self.pdf.w - self.pdf.l_margin - self.pdf.r_margin) / ncol)
+        # b_margin = b_margin + footer_height + footer_top_margin
+        cell_height = (self.pdf.h - self.pdf.b_margin - self.used_top_height) / nrow
+
+        for row_indx in range (nrow):
+            for col_indx in range(ncol):
+                cell = layout[row_indx][col_indx]
+
+                if cell is None:
+                    continue
+
+                rowspan = cell.get("rowspan", 1)
+                colspan = cell.get("colspan", 1)
+
+                width = colspan * cell_width
+                height = rowspan * cell_height
+
+                x = col_indx * cell_width + self.pdf.l_margin # sets from left
+                y = row_indx * cell_height + self.used_top_height # sets from top
+
+                result[(row_indx, col_indx)] = {
+                    "x": x,
+                    "y": y,
+                    "width": width,
+                    "height": height
+                }
+
+        return result
+
+    def get_default_layout(self):
+        """
+        Gets the position (x, y) and available size (width, height) for a chapter or report,
+        considering headers and footers to determine the exact placement of its content (child object).
+        """
+        available_width = self.pdf.w - self.pdf.l_margin - self.pdf.r_margin
+        available_height = self.pdf.h - self.pdf.t_margin - self.pdf.b_margin - self.used_top_height
+
+        x = self.pdf.l_margin
+        y = self.used_top_height + self.pdf.t_margin
+
+        return x, y, available_width, available_height

rephorm/utility/report/range_utility.py

@@ -0,0 +1,94 @@
+import warnings
+
+def _get_max_span(obj, span, comparison):
+
+    if not hasattr(comparison, "frequency"):
+        return span
+
+    obj_frequency = (
+        getattr(obj.settings.span, "frequency", None)
+        or getattr(obj.settings, "frequency", None)
+    )
+
+    if comparison.frequency is not None and obj_frequency is not None:
+        if comparison.frequency != obj_frequency:
+            warnings.warn("Multiple frequencies are not allowed.")
+            return span
+
+    if span is None:
+        span = comparison
+        return span
+
+    start = min(span.start, comparison.start)
+    end = max(span.end, comparison.end)
+
+    return start >> end
+
+# Method for Table and Chart
+def get_span(obj):
+    span = None
+
+    def resolve_span_recursive(node, current_span):
+        if hasattr(node, "settings") and hasattr(node.settings, "span") and hasattr(node, "data") and hasattr(node.data, "span"):
+
+            comparison = node.settings.span.resolve(node.data.span)
+            current_span = _get_max_span(obj, current_span, comparison)
+
+        if hasattr(node, "CHILDREN"):
+            for child in node.CHILDREN:
+                current_span = resolve_span_recursive(child, current_span)
+
+        return current_span
+
+    span = resolve_span_recursive(obj, span)
+
+    # if hasattr(obj, "settings") and hasattr(obj.settings, "span"):
+    if ".start" in str(obj.settings.span.start):
+        obj.settings.span = span.start >> obj.settings.span.end
+
+    if ".end" in str(obj.settings.span.end):
+        obj.settings.span = obj.settings.span.start >> span.end
+
+    if obj.settings.span.start > obj.settings.span.end:
+        raise Exception(
+            f"Invalid highlight range for {obj.__class__.__name__}: Start date ({obj.settings.span.start}) is after the end date ({obj.settings.span.end}). "
+            f"Please provide a highlight range where start precedes the end. "
+            f"Current range: {obj.settings.span.start} >> {obj.settings.span.end}"
+        )
+
+    return obj.settings.span
+
+# Method for Table and Chart
+def get_highlight(obj):
+
+    if obj.settings.highlight is None:
+        return # Just exit the function
+
+    span = get_span(obj)
+
+    if span is None:
+        raise Exception(f"{obj.__class__.__name__} span is missing.")
+
+    start = obj.settings.highlight.start
+
+    if ".start" in str(start):
+        start = span.start
+
+    if start not in span:
+        # We just warn user. But this start not in span is not a problem, because we return min/max
+        # It is just for user to know of issue
+        warnings.warn(f"{obj.__class__.__name__} highlight start is outside the selected span.", UserWarning)
+
+    end = obj.settings.highlight.end
+
+    if ".end" in str(end):
+        end = span.end
+
+    if start > end:
+        raise Exception(
+            f"Invalid highlight range for {obj.__class__.__name__}: Start date ({start}) is after the end date ({end}). "
+            f"Please provide a highlight range where start precedes the end. "
+            f"Current range: {start} >> {end}"
+        )
+
+    return max(start, span.start), min(end, span.end)