rephorm 1.0.1__py3-none-any.whl

rephorm/__init__.py

@@ -0,0 +1,19 @@
+# from .report import *
+from rephorm.objects.report import Report
+from rephorm.objects.table_section import TableSection
+from rephorm.objects.table import Table
+from rephorm.objects.page_break import PageBreak
+from rephorm.objects.grid import Grid
+from rephorm.objects.chart import Chart
+from rephorm.objects.chapter import Chapter
+from .objects.text import Text
+from rephorm.objects.footnote import Footnote
+from rephorm.objects.chart_series import ChartSeries
+from rephorm.objects.table_series import TableSeries
+
+__version__ = "1.0.1"
+__author__ = 'OGResearch team'
+__credits__ = 'OGResearch'
+__license__ = 'Copyright 2025 OGResearch, all rights reserved'
+
+

rephorm/decorators/settings_validation.py

@@ -0,0 +1,49 @@
+import inspect
+
+from rephorm.object_params.settings import object_params
+
+def validate_kwargs(func):
+    """
+    A decorator that validates kwargs (keys and values).
+    It uses ultimate_setting_owner dict!
+    """
+    def wrapper(*args, **kwargs):
+        module_name = func.__module__.split('.')[-1].upper()
+
+        signature = inspect.signature(func)
+        excluded_keys = set(signature.parameters.keys())
+
+        for key, value in kwargs.items():
+
+            # Skip validation for object args/params (We want to validate only kwargs)
+            if key in excluded_keys and key not in object_params:
+                continue
+
+            # Validate key | If the key is within object_params (allowed keys)
+            if key not in object_params:
+                raise KeyError(f"{module_name}: Invalid key '{key}'. "
+                               f"Allowed keys are: {list(object_params.keys())}")
+
+            # Get the expected type from ultimate_setting_owner
+            expected_type = object_params[key]["type"]
+            object_params_key = object_params[key]
+
+            # Validate value type
+            # to skip type-checking for complex types
+            if expected_type is None:
+                continue
+            if not isinstance(value, expected_type):
+                raise TypeError(
+                    f"{module_name}: Argument '{key}' must be of type {expected_type.__name__}, "
+                    f"got {type(value).__name__} instead."
+                )
+
+            # Validate possible values | if they are defined within the object_params
+            if "possible_values" in object_params_key and value not in object_params_key["possible_values"]:
+                possible_values = object_params_key["possible_values"]
+                raise ValueError(
+                    f"{module_name}: Argument '{key}' has invalid value '{value}'. Allowed values are: {possible_values}")
+
+        return func(*args, **kwargs)
+
+    return wrapper

rephorm/dict/__init__.py

@@ -0,0 +1 @@
+#

rephorm/dict/colors.py

@@ -0,0 +1,22 @@
+# Matlab default colors: https://nl.mathworks.com/help/matlab/creating_plots/specify-plot-colors.html
+# Keep codes in hex format here, because FontFace do not accept rgb or rgba, (and we use it for text)
+# for charts and plotly we do conversion to rgba in resolve_highlight_color
+
+color_codes = {
+    "red": "#FF0000",
+    "r": "#FF0000",
+    "green": "#00FF00",
+    "g": "#00FF00",
+    "blue": "#0000FF",
+    "b": "#0000FF",
+    "cyan": "#00FFFF",
+    "c": "#00FFFF",
+    "magenta": "#FF00FF",
+    "m": "#FF00FF",
+    "yellow": "#FFFF00",
+    "y": "#FFFF00",
+    "black": "#000000",
+    "k": "#000000",
+    "white": "#FFFFFF",
+    "w": "#FFFFFF"
+}

rephorm/dict/legend_positions.py

@@ -0,0 +1,136 @@
+legend_positions = {
+    # Center positions
+    "C": {  # Center (Inline)
+        "x": 0.5,
+        "y": 0.5,
+        "xanchor": "center",
+        "yanchor": "middle",
+        "yref": "paper"
+    },
+    # Inside positions
+    "N": {  # North (Top-Center)
+        "x": 0.5,
+        "y": 1,
+        "xanchor": "center",
+        "yanchor": "top",
+        "yref": "paper"
+    },
+    "S": {  # South (Bottom-Center)
+        "x": 0.5,
+        "y": 0,
+        "xanchor": "center",
+        "yanchor": "bottom",
+        "yref": "paper"
+    },
+    "E": {  # East (Right-Center)
+        "x": 1,
+        "y": 0.5,
+        "xanchor": "right",
+        "yanchor": "middle",
+        "yref": "paper"
+    },
+    "W": {  # West (Left-Center)
+        "x": 0,
+        "y": 0.5,
+        "xanchor": "left",
+        "yanchor": "middle",
+        "yref": "paper"
+    },
+    "NE": {  # North-East (Top-Right)
+        "x": 1,
+        "y": 1,
+        "xanchor": "right",
+        "yanchor": "top",
+        "yref": "paper"
+    },
+    "NW": {  # North-West (Top-Left)
+        "x": 0,
+        "y": 1,
+        "xanchor": "left",
+        "yanchor": "top",
+        "yref": "paper"
+    },
+    "SE": {  # South-East (Bottom-Right)
+        "x": 1,
+        "y": 0,
+        "xanchor": "right",
+        "yanchor": "bottom",
+        "yref": "paper"
+    },
+    "SW": {  # South-West (Bottom-Left)
+        "x": 0,
+        "y": 0,
+        "xanchor": "left",
+        "yanchor": "bottom",
+        "yref": "paper"
+    },
+
+    # Outside positions
+    "NO": {  # North-Outside (Above Top-Center)
+        "x": 0.5,
+        "y": 0.89,
+        "xanchor": "center",
+        "yanchor": "top",
+        "yref": "container"
+    },
+    "SO": {  # South-Outside (Below Bottom-Center)
+        "x": 0.5,
+        # "y": 0,
+        "xanchor": "center",
+        # "yanchor": "bottom",
+        # "yref": "container"
+    },
+    # South-Outside (ADJUSTED) Need proper testing
+    # TODO: Consider changing back to "paper" and off-setting POS using negatives.
+    # "SO": {
+    #     "x": 0.5,
+    #     "y": -0.15,
+    #     "xanchor": "center",
+    #     "yanchor": "top",
+    #     "yref": "paper"
+    # },
+    "EO": {  # East-Outside (Right of Chart)
+        "x": 0.8,
+        "y": 0.5,
+        "xanchor": "left",
+        "yanchor": "middle",
+        "yref": "container",
+        "xref": "container"
+    },
+    "WO": {  # West-Outside (Left of Chart)
+        "x": 0,
+        "y": 0.5,
+        "xanchor": "left",
+        "yanchor": "middle",
+        "yref": "container",
+        "xref": "container"
+    },
+    "NEO": {  # North-East-Outside (Above Top-Right)
+        "x": 1,
+        "y": -0.1,
+        "xanchor": "right",
+        "yanchor": "top",
+        "yref": "container"
+    },
+    "NWO": {  # North-West-Outside (Above Top-Left)
+        "x": 0,
+        "y": -0.1,
+        "xanchor": "left",
+        "yanchor": "top",
+        "yref": "container"
+    },
+    "SEO": {
+    "x": 1,
+    "y": 0,
+    "xanchor": "right",
+    "yanchor": "bottom",
+    "yref": "container",
+    },
+    "SWO": {  # South-West-Outside (Below Bottom-Left)
+        "x": 0,
+        "y": 0,
+        "xanchor": "left",
+        "yanchor": "bottom",
+        "yref": "container"
+    }
+}

rephorm/dict/styles.py

@@ -0,0 +1,206 @@
+DEFAULT_FONT_FAMILY = "Helvetica" # This was agreed upon
+
+def default_styles(font_family=DEFAULT_FONT_FAMILY):
+    return {
+        "table": {
+            "highlight_color": "#E0E0E0",
+            "title": {
+                "font_style": "B",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 13,
+            },
+            "heading": {
+                "font_style": "",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 10,
+                "highlight_color": "#E0E0E0",
+            },
+            "series": {
+                "font_style": "",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 10,
+                "highlight_color": "#E0E0E0",
+            },
+            "section": {
+                "font_style": "",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 10,
+                "highlight_color": "#E0E0E0",
+            }
+        },
+        "text": {
+            "font_style": "",
+            "font_family": font_family,
+            "font_size": 10,
+            "title": {
+                "font_style": "B",
+                "font_family": font_family,
+                "font_size": 16,
+            }
+        },
+        "footnotes": {
+            "font_size": 8,
+            "font_color": "#000000",
+            "font_style": "",
+            "font_family": font_family,
+        },
+        "grid": {
+            "title": {
+                "font_style": "B",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 13,
+            },
+        },
+        "chapter": {
+            "title": {
+                "font_style": "B",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 16,
+            },
+            "font_style": "",
+            "font_family": font_family,
+            "font_size": 11,
+        },
+        "chart": {
+            "highlight_color": "rgba(0, 0, 0, 0.12)",
+            "grid_color": "lightgrey",
+            "bg_color": "rgba(0, 255, 0, 0)",
+            "chart_border_color": "#000000",
+            "line_styles_order": [
+                "solid"
+            ],
+            "line_color_order": [
+                "rgb(31, 119, 180)",
+                "rgb(255, 127, 14)",
+                "rgb(44, 160, 44)",
+                "rgb(214, 39, 40)",
+                "rgb(148, 103, 189)",
+                "rgb(140, 86, 75)",
+                "rgb(227, 119, 194)",
+                "rgb(127, 127, 127)",
+                "rgb(188, 189, 34)",
+                "rgb(23, 190, 207)"
+            ],
+            "bar_color_order": [
+                "rgb(31, 119, 180)",
+                "rgb(255, 127, 14)",
+                "rgb(44, 160, 44)",
+                "rgb(214, 39, 40)",
+                "rgb(148, 103, 189)",
+                "rgb(140, 86, 75)",
+                "rgb(227, 119, 194)",
+                "rgb(127, 127, 127)",
+                "rgb(188, 189, 34)",
+                "rgb(23, 190, 207)"
+            ],
+            "line_width_order": [1],
+            "series": {
+                "bar_edge_color": "black",
+                "bar_face_color": None,
+                "bar_edge_width": 1.0,
+                "line_width": None,
+                "line_style": None,
+                "line_color": None,
+                "marker_color": "#46b336",
+                "marker_size": 1,
+                "marker_width": 1,
+            },
+            "legend": {
+                "border_width": 0,
+                "bg_color": "rgba(255, 255, 255, 0)",
+                "font_style": "",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 8,
+            },
+            "title": {
+                "font_style": "",
+                "font_family": font_family,
+                "font_color": "#000000",
+                "font_size": 11,
+            },
+            "x_axis": {
+                "ticks": {
+                    "font_size": 10,
+                    "font_color": "#000000",
+                    "font_family": font_family,
+                },
+                "label": {
+                    "font_size": 10,
+                    "font_color": "#000000",
+                    "font_family": font_family,
+                }
+            },
+            "y_axis": {
+                "ticks": {
+                    "font_size": 10,
+                    "font_color": "#000000",
+                    "font_family": font_family,
+                },
+                "label": {
+                    "font_size": 10,
+                    "font_color": "#000000",
+                    "font_family": font_family,
+                },
+            },
+            "y_axis2": {
+                "ticks": {
+                    "font_size": 10,
+                    "font_color": "#000000",
+                    "font_family": font_family,
+
+                },
+                "label": {
+                    "font_size": 10,
+                    "font_color": "#000000",
+                    "font_family": font_family,
+                }
+            },
+        },
+        "report": {
+            # only front page title
+            "title": {
+                "font_style": "B",
+                "font_size": 25,
+                "font_color": "#000000",
+                "font_family": font_family,
+            },
+            "subtitle": {
+                "font_style": "B",
+                "font_size": 21,
+                "font_color": "#000000",
+                "font_family": font_family,
+            },
+            "abstract": {
+                "height": 50,
+                "font_size": 10,
+                "font_color": "#000000",
+                "font_family": font_family,
+            },
+            "footer": {
+                "height": 15,
+                "top_margin": 5,
+                "top_padding": 5,
+            },
+            "header": {
+                "height": 20,
+                "bottom_margin": 5,
+            },
+            "font_style": "",
+            "font_family": font_family,
+            "font_color": "#000000",
+            "page_margin_top": 10,
+            "page_margin_right": 40,
+            "page_margin_bottom": 15,
+            "page_margin_left": 40,
+            #Todo: Find a better name for it.
+            "title_bottom_padding": 10,
+            "logo_height": 15,
+        }
+    }

rephorm/dict/update_layout.py

@@ -0,0 +1,129 @@
+from rephorm.dict.legend_positions import legend_positions
+from rephorm.utility.report.resolve_color import resolve_color
+
+def update_layout(title, settings, figure, y_range = None):
+
+    # Todo: extract this, but basically this is how to get title style in plotly for chart or for label too (I guess same way for label)
+    font_style = settings.styles["chart"]["title"]["font_style"]
+    if font_style == "B":
+        formatted_title = f"<b>{title}</b>"
+    elif font_style == "I":
+        formatted_title = f"<i>{title}</i>"
+    elif font_style == "BI":
+        formatted_title = f"<b><i>{title}</i></b>"
+    else:
+        formatted_title = title
+
+    layout = {
+                "title": {
+                    "text": formatted_title,
+                    "yref": "container",  # stop overlaps with plot area
+                    "yanchor": "top", # align to top
+                    "x": 0.5,
+                    "automargin": True,  # adjust margins
+                    "pad": {"b": 5},  # Fine control
+                    "font_size": settings.styles["chart"]["title"]["font_size"],
+                    "font_family": settings.styles["chart"]["title"]["font_family"],
+                    "font_color": resolve_color(settings.styles["chart"]["title"]["font_color"]),
+                },
+                "plot_bgcolor": resolve_color(settings.styles["chart"]["bg_color"]),
+                # paper_bgcolor is kinda useless for us now,
+                # because of PDF image choice it will not support transparent bg
+                # https://github.com/plotly/Kaleido/issues/91
+                "paper_bgcolor": 'hsla(0, 100%, 50%, 0)',
+                "margin": {"l": 0,
+                           "r": 0,
+                           "t": 5,
+                           "b": 0
+                           },
+                "xaxis": {
+                    # TODO: Later on introduce this parameter, to set number of ticks manually.
+                    # "nticks": settings.styles["chart"]["x_axis"]["ticks"]["nticks"],
+                    "showgrid": settings.show_grid if settings.show_grid else True,
+                    "gridcolor": resolve_color(settings.styles["chart"]["grid_color"]),
+                    "mirror": settings.axis_border,
+                    "linecolor": resolve_color(settings.styles["chart"]["chart_border_color"]),
+                    "showline": True,
+                    "ticks": "inside",
+                    "tickcolor": "black",
+                    "linewidth": 1,
+                    "tickwidth": 1,
+                    "griddash": "dot",
+                    "gridwidth": 1,
+                    "tickfont": {"size": settings.styles["chart"]["x_axis"]["ticks"]["font_size"],
+                                 "family": settings.styles["chart"]["x_axis"]["ticks"]["font_family"],
+                                 "color": settings.styles["chart"]["y_axis"]["ticks"]["font_color"]},
+                    "title": {
+                        "text": settings.xaxis_title,
+                        "font": {
+                            "size": settings.styles["chart"]["x_axis"]["label"]["font_size"],
+                            "family": settings.styles["chart"]["x_axis"]["label"]["font_family"]}},
+                },
+                "yaxis": {
+                    "zeroline": settings.zeroline if hasattr(settings, 'zeroline') else True,
+                    "showgrid": settings.show_grid if hasattr(settings, 'show_grid') else True,
+                    "gridcolor": resolve_color(settings.styles["chart"]["grid_color"]),
+                    "mirror": settings.axis_border,
+                    "linecolor": resolve_color(settings.styles["chart"]["chart_border_color"]),
+                    "showline": True,
+                    "ticks": "inside",
+                    "tickcolor": "black",
+                    "linewidth": 1,
+                    "tickwidth": 1,
+                    "griddash": "dot",
+                    "gridwidth": 1,
+                    "range": y_range,
+                    "tickfont": {"size": settings.styles["chart"]["y_axis"]["ticks"]["font_size"],
+                                 "family": settings.styles["chart"]["y_axis"]["ticks"]["font_family"],
+                                 "color": settings.styles["chart"]["y_axis"]["ticks"]["font_color"]},
+                    "title": {
+                        "text": settings.yaxis_title,
+                        "font": {
+                            "size": settings.styles["chart"]["y_axis"]["label"]["font_size"],
+                            "family": settings.styles["chart"]["y_axis"]["label"]["font_family"]}},
+                },
+                "yaxis2": {
+                    "overlaying": "y",
+                    "side": "right",
+                    "linecolor": resolve_color(settings.styles["chart"]["chart_border_color"]),
+                    "showline": True,
+                    "ticks": "inside",
+                    "tickcolor": "black",
+                    "linewidth": 1,
+                    "tickwidth": 1,
+                    "range": y_range,
+                    "tickfont": {"size": settings.styles["chart"]["y_axis2"]["ticks"]["font_size"],
+                                 "family": settings.styles["chart"]["y_axis2"]["ticks"]["font_family"],
+                                 "color": settings.styles["chart"]["y_axis2"]["ticks"]["font_color"]},
+                    "title": {
+                        "text": settings.yaxis2_title,
+                        "font": {
+                            "size": settings.styles["chart"]["y_axis2"]["label"]["font_size"],
+                            "family": settings.styles["chart"]["y_axis2"]["label"]["font_family"]}},
+                },
+                "legend": {
+                    "font": {
+                        "size": settings.styles["chart"]["legend"]["font_size"],
+                        "family": settings.styles["chart"]["legend"]["font_family"],
+                        "color": resolve_color(settings.styles["chart"]["legend"]["font_color"])
+                    },
+                    "orientation": settings.legend_orientation.lower(),
+                    "x": legend_positions.get(settings.legend_position.upper()).get("x"),
+                    "y": legend_positions.get(settings.legend_position.upper()).get("y"),
+                    "xanchor": legend_positions.get(settings.legend_position.upper()).get("xanchor"),
+                    "yanchor": legend_positions.get(settings.legend_position.upper()).get("yanchor"),
+                    "borderwidth": settings.styles["chart"]["legend"]["border_width"],
+                    "yref": legend_positions.get(settings.legend_position.upper()).get("yref"),
+                    "xref": legend_positions.get(settings.legend_position.upper()).get("xref"),
+                    "bgcolor": resolve_color(settings.styles["chart"]["legend"]["bg_color"]),
+                }
+            }
+
+    # Update conditionally only if the user explicitly specifies 'ncols'.
+    legend_ncol = settings.legend_ncol
+    if bool(legend_ncol):
+        figure.layout.legend["entrywidth"] = 1 / legend_ncol
+        figure.layout.legend["entrywidthmode"] = "fraction"
+
+    figure.update_layout(layout)
+

rephorm/dict/update_traces.py

@@ -0,0 +1,90 @@
+"""
+Prepare shared (base-level) trace update settings for Plotly plots.
+
+This function returns general trace configuration that applies uniformly
+across all traces — where no fine-grained (per-trace) control is needed
+between multivariate and single-series cases.
+
+"""
+def update_base_traces(settings):
+    yaxis = getattr(settings, "yaxis", "left")
+    if settings.series_type == "line":
+         update_traces = {
+            "mode": settings.markers_mode,
+            "marker": {
+                "symbol": settings.marker_symbol,
+                "size": settings.styles["chart"]["series"]["marker_size"],
+                "line.width": settings.styles["chart"]["series"]["marker_width"],
+                "line.color": settings.styles["chart"]["series"]["marker_color"],
+                "color": settings.styles["chart"]["series"]["marker_color"],
+            },
+            "marker.color": settings.styles["chart"]["series"]["marker_color"],
+            "yaxis": "y2" if yaxis == "right" else "y1"
+            }
+    elif "bar" in settings.series_type.lower():
+         update_traces = {
+            "type": "bar",
+            "marker": {
+                "line.color": settings.styles["chart"]["series"]["bar_edge_color"],
+                "line.width": settings.styles["chart"]["series"]["bar_edge_width"],
+            },
+              "yaxis": "y2" if yaxis == "right" else "y1"
+        }
+    else: update_traces = {}
+
+    return update_traces
+
+def apply_per_trace_styles(
+    fig,
+    line_colors=None,
+    line_widths=None,
+    line_styles=None,
+    bar_colors=None,
+    num_variants=None,
+):
+    """
+    Apply per-trace styling to a Plotly figure.
+
+    Supports passing a single value or a list for each style type.
+    """
+
+    if not fig.data:
+        return
+
+    traces = fig.data[-num_variants:]
+
+    for idx, trace in enumerate(traces):
+
+        if trace.type == 'scatter':
+
+            color = get_value(line_colors, idx)
+            if color:
+                trace.line.color = color
+
+            width = get_value(line_widths, idx)
+            if width:
+                trace.line.width = width
+
+            dash = get_value(line_styles, idx)
+            if dash:
+                trace.line.dash = dash
+
+        elif trace.type == 'bar':
+            color = get_value(bar_colors, idx)
+            if color:
+                trace.marker.color = color
+
+
+def get_value(value, i):
+    """
+    Function to retrieve the appropriate style value for the n-th trace.
+    Mainly used for apply_per_trace_styles()
+
+    :param value: Either a single value or a list of values.
+    :param i: trace index
+    :return: value (str)
+    """
+    if isinstance(value, list):
+        # If a list, return value based on trace index, and cycle
+        return value[i % len(value)]
+    else: return value  # bcs single value can also be passed

rephorm/object_mappers/_globals.py

@@ -0,0 +1,16 @@
+# central storage for globals
+from os.path import defpath
+
+figure_map = []
+
+def set_figure_map(data):
+    global figure_map
+    figure_map.append(data)
+
+def get_figure_map():
+    global figure_map
+    return figure_map
+
+def reset_figure_map():
+    global figure_map
+    figure_map = []