rephorm 1.0.1__py3-none-any.whl

rephorm/objects/chart_series.py

@@ -0,0 +1,40 @@
+from irispie import Series as IrisSeries
+
+from rephorm.object_mappers.chart_series_mapper import ChartSeriesMapper
+from rephorm.objects._utilities.settings_container import SettingsContainer
+from rephorm.decorators.settings_validation import validate_kwargs
+from rephorm.utility.add_style_prefix import add_prefix_to_styles
+
+
+class ChartSeries:
+
+    @validate_kwargs
+    def __init__( self, data: IrisSeries = None, **kwargs):
+        """
+            :param data (IrisSeries, Required): Data for the chart series.
+            :key yaxis (str, Optional): Y-axis position for the chart series. Defaults to "left".
+            :key span (ir.Span): Span of the chart series.
+            :key show_legend (bool): to show/hide the legend for this data series.
+            :key legend (tuple): Specifies the legend labels for the series. For a single series, use ("Label",).
+            For multivariate series, provide multiple labels like ("Label 1", "Label 2", ...).
+            :key highlight (ir.Span): Span of the highlight.
+            :key series_type (str): Type of series to display - "line" for line charts, "bar" for bar charts,
+            "bar_contribution" for contribution bar charts; use "line" with markers_mode="markers" for marker-based charts.
+            :key markers_mode (str): Display style for data points - "lines+markers" (lines with symbols/dots),
+            "lines" (lines only), or "markers" (symbols/dots only).
+            :key marker_symbol (str): Symbol used for markers in the series. e.g., "asterisk".
+            :key update_traces (Dict): Traces configuration for the chart series. (Plotly specific) todo: check if this is used
+            :key styles (Dict): Styles dictionary for additional customization (for details refer to report object).
+        """
+
+        self.data = data
+        self.settings = SettingsContainer(**kwargs)
+
+        if hasattr(self.settings, "styles"):
+            self.settings.styles = add_prefix_to_styles("chart.series", self.settings.styles)
+
+    def _get_mapper(self):
+        return ChartSeriesMapper(self)
+
+    def __repr__(self):
+        return f"{type(self).__name__}"

rephorm/objects/footnote.py

@@ -0,0 +1,13 @@
+class Footnote:
+    # ----------------------------------
+    # Class initiator
+    # ----------------------------------
+
+    def __init__(
+        self,
+        text: str = "",
+    ):
+        self.TEXT = text
+
+    def __repr__(self):
+        return f"{type(self).__name__}"

rephorm/objects/grid.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+import copy
+from typing import Text, Optional, Union, List
+
+from rephorm.objects.table import Table
+from rephorm.objects.text import Text
+from rephorm.objects.page_break import PageBreak
+from rephorm.objects.chart import Chart
+from rephorm.object_mappers.grid_mapper import GridMapper
+from rephorm.objects._utilities.settings_container import SettingsContainer
+from rephorm.decorators.settings_validation import validate_kwargs
+from rephorm.utility.add_style_prefix import add_prefix_to_styles
+
+
+class Grid:
+
+    @validate_kwargs
+    def __init__(self, title: str = "", footnotes: Optional[List[str]] = None, **kwargs):
+        """
+            :param title: (str) Title of the grid.
+            :param footnotes: (Tuple(str)) Footnotes for the title.
+            :key ncol (int): Number of columns in the grid.
+            :key nrow (int): Number of rows in the grid.
+            :key layout (Dict): layout configuration for the chart (see documentation).
+            :key styles (Dict): Styles dict (refer to documentation).
+        """
+        self.title = title
+        self.CHILDREN = []
+        self.footnotes = footnotes
+        self.settings = SettingsContainer(**kwargs)
+        if hasattr(self.settings, "styles"):
+            self.settings.styles = add_prefix_to_styles("grid", self.settings.styles)
+
+    def add(
+        self,
+        grid_child : Union[Grid, Table, Text, PageBreak, Chart] = None,
+    ):
+
+        #12/10/2024: We should have checks in the objects and not object mappers
+        # We would also not have problem with imports here, because this module itself is within OBJECTS
+        # Todo: Update latest docs, explaining it is not possible to nest grids within grids, and the reason why.
+        if grid_child is not None and isinstance(grid_child, (Table, Text, PageBreak, Chart)):
+            # grid_child._on_add_callback()
+            copy_grid_child = copy.deepcopy(grid_child)
+            self.CHILDREN.append(copy_grid_child)
+        else: raise Exception("Grid: grid child of wrong type or None")
+
+
+    def _get_mapper(self):
+        return GridMapper(self)
+
+    def __repr__(self):
+        return f"{type(self).__name__}"
+
+    def _on_add_callback(self):
+        pass
+    # This would be called by whoever is adding the grid object.

rephorm/objects/page_break.py

@@ -0,0 +1,13 @@
+from rephorm.object_mappers.page_break_mapper import PageBreakMapper
+
+
+class PageBreak:
+
+    def __init__(self, ):
+        pass
+
+    def _get_mapper(self):
+        return PageBreakMapper(self)
+
+    def __repr__(self):
+        return f"{type(self).__name__}"

rephorm/objects/report.py

@@ -0,0 +1,196 @@
+import copy
+from typing import Optional, Dict, Text, Union
+
+from rephorm.objects.grid import Grid
+from rephorm.objects.table import Table
+from rephorm.objects.text import Text
+from rephorm.objects.page_break import PageBreak
+from rephorm.objects.chart import Chart
+from rephorm.objects.chapter import Chapter
+
+from rephorm.objects._utilities.settings_container import SettingsContainer
+from rephorm.utility.add_style_prefix import add_prefix_to_styles
+from rephorm.utility.fonts.font_loading import get_fonts, add_custom_fonts
+from rephorm.object_mappers.report_mapper import ReportMapper
+from rephorm.utility.PDF import PDF
+from rephorm.utility.merge.merge_settings import merge_settings
+from rephorm.decorators.settings_validation import validate_kwargs
+
+
+class Report:
+    @validate_kwargs
+    # Todo: delete report name from here, it is not needed since you can specify it on output method call
+    def __init__(self, title: str = "", subtitle: str = "", load_fonts: Optional[list[Dict[str, str]]] = None, abstract: str="", **kwargs):
+        # Todo: consider moving `load_fonts` to `kwargs` (Currently, it would be hard to validate entry/value if we move to kwargs, bcs of it's complex value type)
+        # Todo: add new setting `show_title_page=True` to control whether to create the front page or not (and make sure the header creation is aware of this parameter)
+        """
+            **Params:**
+                - ``title`` (str): Title of the report. Placed in the front page.
+                - ``subtitle`` (str): Subtitle of the report. Placed in the front page after the title.
+                - ``load_fonts`` (list[Dict[str, str]]): Fonts to load for the report.
+                 For ``load_fonts`` you need to specify font_family, font_style and font_path as dictionary.
+
+            **Kwargs:**
+                - ``orientation`` (str): Orientation of the report, e.g., 'P' for Portrait, 'L' for Landscape.
+                - ``unit`` (str): Measurement unit for the report, e.g., 'pt', 'mm', 'cm'.
+                - ``format`` (str): Paper format for the report, e.g., 'A4', 'Letter'.
+                - ``logo`` (str): Path to the logo file for the report.
+                - ``styles`` (Dict): Styles dictionary for additional customization. See below for keys.
+
+            **Styles Dictionary Keys:**
+
+            **Table**
+                *title*
+                    - ``table.title.font_style`` (str)
+                    - ``table.title.font_family`` (str)
+                    - ``table.title.font_color`` (str)
+                    - ``table.title.font_size`` (float)
+
+                *heading*
+                    - ``table.heading.font_style`` (str)
+                    - ``table.heading.font_family`` (str)
+                    - ``table.heading.font_color`` (str)
+                    - ``table.heading.font_size`` (float)
+                    - ``table.heading.highlight_color`` (str): color name
+
+                *series*
+                    - ``table.series.font_style`` (str)
+                    - ``table.series.font_family`` (str)
+                    - ``table.series.font_color`` (str)
+                    - ``table.series.font_size`` (float)
+                    - ``table.series.highlight_color`` (str): color name
+
+                **section**
+                    - ``table.section.font_family`` (str)
+                    - ``table.section.font_color`` (str)
+                    - ``table.section.font_size`` (float)
+                    - ``table.section.highlight_color`` (str): color name
+
+            **Chart:**
+                **general**
+                    - ``chart.highlight_color`` (str)
+                    - ``chart.grid_color`` (str)
+                    - ``chart.bg_color`` (str): Background color of the chart.
+                    - ``chart.chart_border_color`` (str): Border color of the chart. If border is applied
+                **legend**
+                    - ``chart.legend.border_width`` (int):
+                    - ``chart.legend.bg_color`` (str):
+                    - ``chart.legend.font_style`` (str):
+                    - ``chart.legend.font_family`` (str):
+                    - ``chart.legend.font_color`` (str):
+                    - ``chart.legend.font_size`` (float):
+
+                **title**
+                    - ``chart.title.font_style`` (str)
+                    - ``chart.title.font_family`` (str)
+                    - ``chart.title.font_color`` (str)
+                    - ``chart.title.font_size`` (float)
+
+                **x_axis:**
+                    *ticks:*
+                        - ``chart.x_axis.ticks.font_size`` (float)
+                        - ``chart.x_axis.ticks.font_color`` (str)
+                        - ``chart.x_axis.ticks.font_family`` (str)
+                    *label:*
+                        - ``chart.x_axis.label.font_size`` (float)
+                        - ``chart.x_axis.label.font_color`` (str)
+                        - ``chart.x_axis.label.font_family`` (str)
+
+                **y_axis:**
+                    *ticks:*
+                        - ``chart.y_axis.ticks.font_size`` (float)
+                        - ``chart.y_axis.ticks.font_color`` (str)
+                        - ``chart.y_axis.ticks.font_family`` (str)
+                    *label:*
+                        - ``chart.y_axis.label.font_size`` (float)
+                        - ``chart.y_axis.label.font_color`` (str)
+                        - ``chart.y_axis.label.font_family`` (str)
+
+                **series:**
+                    - ``chart.series.bar_edge_color`` (str): Border color for bars in bar charts, default black.
+                    - ``chart.series.bar_edge_width`` (int): Border width for bars in bar charts.
+                    - ``chart.series.bar_face_color`` (str): Fill color for bars in bar charts, default green.
+                    - ``chart.series.line_width`` (int): Line width, default 1.
+                    - ``chart.series.line_style`` (str): 'solid', 'dot', 'dash', 'longdash', 'dashdot', 'longdashdot'.
+                    - ``chart.series.line_color`` (str): Color of the line.
+                    - ``chart.series.marker_color`` (str): Color of the marker symbol.
+                    - ``chart.series.marker_size`` (int): Size of the marker symbol.
+                    - ``chart.series.marker_width`` (int): Marker width default is 0; some, like asterisks, require a width of 1.
+
+            **Report:**
+                - ``report.font_style`` (str)
+                - ``report.font_family`` (str)
+                - ``report.font_color`` (str)
+                - ``report.font_size`` (float)
+                - ``report.page_margin_left`` (int)
+                - ``report.page_margin_top`` (int)
+
+            **Text:**
+                - ``text.font_style`` (str): as string: "B", "I", "BI"
+                - ``text.font_family`` (str)
+                - ``text.font_size`` (float)
+
+            **Chapter:**
+                - ``chapter.font_style`` (str)
+                - ``chapter.font_family`` (str)
+                - ``chapter.font_size`` (float)
+
+            :key kwargs (any): You can provide any key-value pair to customize settings. If Object A contains Object B, settings for Object B can be defined in Object A and will apply to all instances of Object B, unless overridden for a specific instance
+        """
+
+        self.CHILDREN = []
+        self.title = title
+        self.subtitle = subtitle
+        self.load_fonts = get_fonts(load_fonts)
+        self.abstract = abstract
+        self.settings = SettingsContainer(**kwargs)
+
+        if hasattr(self.settings, "styles"):
+            self.settings.styles = add_prefix_to_styles("report", self.settings.styles)
+
+        merge_settings(self, self.settings.__dict__)
+
+    def add(self, report_child : Union[Grid, Table, Text, PageBreak, Chart, Chapter] = None):
+        if report_child is not None and isinstance(report_child, (Grid, Table, Text, PageBreak, Chart, Chapter)):
+            copy_report_child = copy.deepcopy(report_child)
+            self.CHILDREN.append(copy_report_child)
+            merge_settings(self, self.settings.__dict__)
+        else: raise Exception("Report: report child of wrong type or None")
+
+    # TODO: Output needs to know about mapper, so regarding circularity, extracting output would help us.
+    # Should be part of report mapper
+    def output(self, file_name: str = "report", cleanup: bool = True):
+        """
+            :args file_name (str): name of the report output file
+            :args cleanup (bool): if True, figures will be kept within /tmp directory
+        """
+
+        pdf = PDF(
+            orientation = self.settings.orientation,
+            unit = self.settings.unit,
+            format = self.settings.format,
+            report_styles=self.settings.styles["report"],
+            report_title=self.title,
+        )
+
+        add_custom_fonts(pdf, self.load_fonts)
+
+        pdf.set_margins(left=self.settings.styles["report"]["page_margin_left"],
+                         top=self.settings.styles["report"]["page_margin_top"])
+
+        reportMapper = ReportMapper(pdf)
+
+        reportMapper.compile(self, file_name, cleanup)
+
+    def set_front_page(self, title: str = "", subtitle: str = "", abstract: str="", logo: Optional[str] = None):
+        if bool(title):
+            self.title = title
+        if bool(subtitle):
+            self.subtitle = subtitle
+        if bool(abstract):
+            self.abstract = abstract
+        if bool(logo):
+            self.settings.logo = logo
+
+
+

rephorm/objects/table.py

@@ -0,0 +1,76 @@
+import copy
+from typing import Optional, List, Union
+
+from rephorm.objects.table_section import TableSection
+from rephorm.objects.table_series import TableSeries
+from rephorm.object_mappers.table_mapper import TableMapper
+from rephorm.objects._utilities.settings_container import SettingsContainer
+from rephorm.utility.add_style_prefix import add_prefix_to_styles
+from rephorm.utility.report.range_utility import get_span, get_highlight
+from rephorm.decorators.settings_validation import validate_kwargs
+from rephorm.utility.report.table_utility import get_table_highlight
+
+
+class Table:
+
+    @validate_kwargs
+    def __init__(self, title: str = "", footnotes: Optional[List[str]] = None, width: int = None, **kwargs):
+        """
+            :param title: Title of the table.
+            :param footnotes: Footnotes for the title.
+            :param width (int): The maximum width allowed for rendering the table.
+            :key span (ir.Span, Required): Span of the table.
+            :key highlight (ir.Span): Span of the highlight.
+            :key show_units (bool): Display/hide units in the table.
+            :key frequency (str): Frequency of the data in the table.
+            :key decimal_precision (int): Sets number of decimal places after the decimal point.
+            :key compare_style (str): Comparison style for the table series. "diff", "pct".
+            :key layout (Dict): Layout configuration for the table (Plotly specific).
+            :key styles (Dict): Styles dictionary for additional customization (for details refer to report object).
+        """
+        self.CHILDREN = []
+        self.footnotes = footnotes
+        self.title = title
+        self.width = width
+        self.settings = SettingsContainer(**kwargs)
+
+        if hasattr(self.settings, "styles"):
+            self.settings.styles = add_prefix_to_styles("table", self.settings.styles)
+
+
+    def add(self, table_child: Union[TableSeries, TableSection] = None,):
+
+        self._on_add_callback()
+
+        if table_child is not None and isinstance(table_child, (TableSeries, TableSection)):
+            copy_table_child = copy.deepcopy(table_child)
+            self.CHILDREN.append(copy_table_child)
+        else:
+            raise Exception("Table: Table child of wrong type or None")
+
+    def _get_mapper(self):
+        return TableMapper(self)
+
+    def _get_span(self):
+        return get_span(self)
+
+    def _get_highlight(self):
+        return get_highlight(self)
+
+    def _get_table_highlight(self):
+        return get_table_highlight(self)
+
+    # Because sometimes we may want to print the name of the object
+    def __repr__(self):
+        return f"{type(self).__name__}"
+
+    def _on_add_callback(self):
+
+        if hasattr(self.settings, 'styles'):
+            highlight_color = self.settings.styles.get("table.highlight_color")
+
+            if highlight_color:
+                # Set default values for various highlight_color properties
+                self.settings.styles.setdefault("table.series.highlight_color", highlight_color)
+                self.settings.styles.setdefault("table.heading.highlight_color", highlight_color)
+                self.settings.styles.setdefault("table.section.highlight_color", highlight_color)

rephorm/objects/table_section.py

@@ -0,0 +1,48 @@
+import copy
+
+from rephorm.object_mappers.table_section_mapper import TableSectionMapper
+from rephorm.objects.table_series import TableSeries
+from rephorm.objects._utilities.settings_container import SettingsContainer
+from rephorm.decorators.settings_validation import validate_kwargs
+from rephorm.utility.add_style_prefix import add_prefix_to_styles
+
+
+class TableSection:
+
+    @validate_kwargs
+    def __init__(self, title: str = None, **kwargs):
+        """
+            :param title: (str) Title of the table section.
+            :key styles (Dict): Styles dictionary for the table section (refer to documentation).
+            :key highlight (ir.Span): Span of the highlight in the table section. (applies to all table_series added within the section)
+            :key show_units (bool): To show/hide units for the table section. (applies to all table_series added within the section)
+        """
+        self.TITLE = title
+        self.CHILDREN = []
+        self.settings = SettingsContainer(**kwargs)
+        if hasattr(self.settings, "styles"):
+            self.settings.styles = add_prefix_to_styles("table.section", self.settings.styles)
+
+    def add (self, table_section_child: TableSeries = None):
+
+        self._on_add_callback()
+
+        if table_section_child is not None and isinstance(table_section_child, TableSeries):
+            copy_table_section_child = copy.deepcopy(table_section_child)
+            self.CHILDREN.append(copy_table_section_child)
+        else:
+            raise Exception("TableSection: Table Section child of wrong type or None")
+
+    def _get_mapper(self):
+        return TableSectionMapper(self)
+
+    def __repr__(self):
+        return f"{type(self).__name__}"
+
+    def _on_add_callback(self):
+        if hasattr(self.settings, 'styles'):
+            highlight_color = self.settings.styles.get("table.section.highlight_color")
+            if highlight_color:
+                self.settings.styles.setdefault("table.series.highlight_color", highlight_color)
+                self.settings.styles.setdefault("table.section.highlight_color", highlight_color)
+

rephorm/objects/table_series.py

@@ -0,0 +1,36 @@
+from irispie import Series as IrisSeries
+
+from rephorm.object_mappers.table_series_mapper import TableSeriesMapper
+from rephorm.objects._utilities.settings_container import SettingsContainer
+from rephorm.decorators.settings_validation import validate_kwargs
+from rephorm.utility.add_style_prefix import add_prefix_to_styles
+
+
+class TableSeries:
+
+    @validate_kwargs
+    def __init__(self, title: str = None, unit: str = None, data: IrisSeries = None, **kwargs):
+        """
+            :param data: (IrisSeries, Required) Data for the table series.
+            :param title: (str) Name of the table series / row.
+            :param unit: (str) The text value for the "units" column in this specific row of the table series.
+            This defines what will be displayed as the unit for the corresponding row.
+            :key span (ir.Span): Span of the table series.
+            :key highlight (ir.Span): Span of the highlight in the table series.
+            :key compare_style (str): Comparison style for the table series. "diff", "pct".
+            :key decimal_precision (int): Sets number of decimal places after the decimal point.
+            :key comparison_series (bool): Whether the series should be displayed as comparison series.
+            :key styles (Dict): Styles dictionary for additional customization (for details refer to report object).
+        """
+        self.data = data
+        self.title = title
+        self.unit = unit
+        self.settings = SettingsContainer(**kwargs)
+        if hasattr(self.settings, "styles"):
+            self.settings.styles = add_prefix_to_styles("table.series", self.settings.styles)
+
+    def _get_mapper(self):
+        return TableSeriesMapper(self)
+
+    def __repr__(self):
+        return f"{type(self).__name__}"

rephorm/objects/text.py

@@ -0,0 +1,35 @@
+from typing import Literal
+from rephorm.decorators.settings_validation import validate_kwargs
+from rephorm.object_mappers.text_mapper import TextMapper
+from rephorm.objects._utilities.settings_container import SettingsContainer
+
+
+class Text:
+    # ----------------------------------
+    # Class initiator
+    # ----------------------------------
+    @validate_kwargs
+    def __init__(
+        self,
+        title: str = "",
+        text: str = "",
+        align: Literal["x", "c", "l", "j", "r"] = "j",
+        markdown = False,
+        **kwargs
+    ):
+        self.title = title
+        self.TEXT = text
+        self.align = align
+        self.markdown = markdown
+        self.settings = SettingsContainer(**kwargs)
+
+    def _get_mapper(self):
+        return TextMapper(self)
+
+    def __repr__(self):
+        return f"{type(self).__name__}"
+
+
+
+
+

rephorm/utility/PDF.py

@@ -0,0 +1,80 @@
+from datetime import datetime
+
+from fpdf import FPDF
+
+"""
+This subclass extends FPDF to include customized header and footer functionality,
+making it easier to apply consistent formatting across all pages of the document.
+By overriding the `header` and `footer` methods, we ensure that these elements
+are automatically added to each page without manual intervention.
+"""
+
+class PDF(FPDF):
+    def __init__(self, report_styles = None, report_title = None, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.report_styles = report_styles
+        self.report_title = report_title
+        self.timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+
+    def header(self):
+        header_height = self.report_styles["header"]["height"]
+        self.set_font(family=self.report_styles["font_family"], size=8)
+        # Todo: here, H should be set to header height
+        # Set absolute position for the header
+        # We need to skip first cell (bcs of logo).
+        header_width = self.epw / 3
+        y = self.get_y()
+
+        layout = self._get_header_layout(self.page_no(), self.timestamp, self.report_title)
+
+        for item in layout:
+            x = self.l_margin + item["slot"] * header_width
+            self.set_xy(x, y)
+            self.cell(
+                w=header_width,
+                h=header_height,
+                text=item["text"],
+                align=item.get("align", "L"),
+                # border=1 #for debugging
+            )
+    # Todo: was easier to extract it like this, and in the future we could rewr this function
+    #  further in order to specify exact positions of elements.
+    def _get_header_layout(self, page_no, timestamp, report_title):
+        layout = [
+            {
+                "id": "title",
+                "text": report_title,
+                "align": "L",
+                "slot": 0
+            },
+            {
+                "id": "page",
+                "text": f"Page {page_no}",
+                "align": "C",
+                "slot": 1
+            },
+            {
+                "id": "timestamp",
+                "text": timestamp,
+                "align": "R",
+                "slot": 2
+            }
+        ]
+
+        # Todo: modify this, once we have show_title_page option on report object that controls whether the
+        #  title page shown or not.
+        if page_no == 1:
+            layout = [{
+                "id": "timestamp",
+                "text": timestamp,
+                "align": "R",
+                "slot": 2
+            }]
+
+        return layout
+
+
+
+
+
+

rephorm/utility/add_style_prefix.py

@@ -0,0 +1,30 @@
+# The 'prefixes' tuple contains the current object name prefixes.
+# When defining styles, avoid using object names as keys.
+# For example, a structure like Grid: { chart: { } }
+# will cause issues, because chart is also an object name.
+
+prefixes = (
+    "chart.",
+    "grid.",
+    "report.",
+    "chapter.",
+    "table.",
+    "text.",
+)
+
+def flatten_dict(d, parent_key='', sep='.'):
+    items = []
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        if isinstance(v, dict):
+            items.extend(flatten_dict(v, new_key, sep=sep).items())
+        else:
+            items.append((new_key, v))
+    return dict(items)
+
+def add_prefix_to_styles(obj_name, styles):
+    flatten_styles = flatten_dict(styles)
+    return {
+        key if key.startswith(prefixes) else f"{obj_name}.{key}": value
+        for key, value in flatten_styles.items()
+    }