basic-report 0.1.0__py3-none-any.whl

basic_report/report.py

@@ -0,0 +1,404 @@
+import datetime
+import shutil
+import yaml
+from loguru import logger
+from pandas import DataFrame
+from pathlib import Path
+from typing import Any, Union, Optional, Literal, Callable
+
+from . import CONFIG_DIR, SCRIPTS_DIR
+from .page import ReportPage
+from .utils import default, verify_color_mode, ColorMap
+
+#----------------------------------------------------------------------------------------------------------------------#
+# region REPORT
+#----------------------------------------------------------------------------------------------------------------------#
+class Report:
+    """ Main report object """
+    def __init__(
+            self,
+            report_dir: Union[str, Path],
+            report_title: Optional[str]=None,
+            report_date: Optional[Union[str, int, datetime.date, datetime.datetime]]=None,
+            config_file: Optional[Union[str, Path]]=None,
+            color_mode: str='light',
+            text_color: Optional[str]=None,
+        ):
+        """ Initialize a new report
+
+        Args:
+            report_dir (Union[str, Path]): The main output dir which will contain the report
+            report_title (Optional[str]): The report title, if None is given it will be called `Unnamed Report`
+            report_date (Optional[Union[str, int, datetime.date, datetime.datetime]]): The report date, if none is given
+                today will be used
+            config_file (Optional[Union[str, Path]]): Path to the user config file that will be used. If none is given
+                the default config file will be read.
+            color_mode (str): Either `light` or `dark.
+            text_color (Optional[str]): Override for the text color of the report. For a more granular approach use the
+                config file
+        """
+        self.report_date  = default(report_date, datetime.date.today())
+        self.report_title = default(report_title, 'Unnamed Report')
+        self.report_dir   = Path(report_dir)
+        self.config       = self._load_config(config_file)
+        self.color_map    = ColorMap(self.config, color_mode, text_color)
+        self.color_mode   = color_mode
+        self.text_color   = text_color
+
+        self.pages: dict[str, ReportPage] = {}
+        self.add_page('main', subpage=False, color_mode=color_mode)
+        self.set_current_page('main')
+
+        self.global_links = []
+
+    #---------------#
+    # Magic Methods #
+    #---------------#
+    def __getitem__(self, key: str) -> ReportPage:
+        """ Simple access to the subpages
+
+        Args:
+            key (str): The page name to access
+
+        Returns:
+            ReportPage - The page object for the given page name
+        """
+        return self.pages[key]
+
+    #---------#
+    # Private #
+    #---------#
+    def _load_config(self, cfg_file: Optional[Union[str, Path]]=None) -> dict[str, Any]:
+        """ Load a report config file
+
+        Args:
+            cfg_file (Optional[Union[str, Path]]): The config file to load. If none is given the default config file
+                will be read
+
+        Returns:
+            dict[str, Any] - The config file content as dict
+        """
+        # Read default config
+        default_cfg_file =  CONFIG_DIR / 'default.yaml'
+        if not default_cfg_file.exists():
+            msg = f'Could not find default config file {default_cfg_file}!'
+            logger.error(msg)
+            raise RuntimeError(msg)
+        with open(default_cfg_file, 'r') as f:
+            default_cfg = yaml.load(f, Loader=yaml.BaseLoader)
+
+        # Read custom config if given
+        if cfg_file is not None:
+            cfg_file = Path(cfg_file)
+            if not cfg_file.exists():
+                msg = f'Could not find default config file {default_cfg_file}!'
+                logger.error(msg)
+                raise RuntimeError(msg)
+            with open(cfg_file, 'r') as f:
+                custom_cfg = yaml.load(f, Loader=yaml.BaseLoader)
+        else:
+            custom_cfg = {}
+
+        cfg = default_cfg
+        for k,v in custom_cfg.items():
+            if k != 'custom_colors':
+                cfg[k] = v
+            else:
+                for ck,cv in v.items():
+                    if ck not in cfg['custom_colors']:
+                        cfg['custom_colors'][ck] = cv
+                    else:
+                        msg = (f'Tried to set color with name {ck}, which is already defined by the report class itself'
+                               f'Please rename the color and try again.')
+                        logger.error(msg)
+                        raise RuntimeError(msg)
+
+        return cfg
+
+    #-----#
+    # API #
+    #-----#
+    # Report structure methods
+    # ------------------------
+    def add_page(self, name: str, subpage: bool=True, color_mode: Optional[str]=None):
+        """ Add a new page to the report
+
+        Args:
+            name (str): The name of the report page
+            subpage (bool): Indicates this is a subpage of the report
+            color_mode (Optional[str]): Color mode of the page, either `light` or `dark`
+        """
+        color_mode = verify_color_mode(default(color_mode, self.color_mode))
+        self.pages[name] = ReportPage(self.report_dir, name, self.config, self.color_map, subpage, color_mode)
+
+    def dump(self):
+        """ Save the report to file and add the CSS files """
+        # Dump all of the report pages
+        for page in self.pages.values():
+            if self.global_links:
+                page._make_global_link_navbar(self.global_links) #noqa: SLF001
+            page._dump() #noqa: SLF001
+
+        # Add the common css files and scripts from the package and the ones created by the color map
+        src = SCRIPTS_DIR
+        dst = self.report_dir / 'css_and_scripts'
+        shutil.copytree(src, dst)
+
+        self.color_map.make_css_files(dst)
+
+    def set_current_page(self, page_name: str):
+        """ Set the current page that is being worked on
+
+        Args:
+            page_name (str): The page you want to switch to
+        """
+        if page_name not in self.pages:
+            msg = f'Unkown page {page_name}. Known: {self.pages.keys()}'
+            logger.error(msg)
+            raise RuntimeError(msg)
+
+        self.current: ReportPage = self.pages[page_name]
+
+    # Headers & special sections
+    # --------------------------
+    def add_report_header(self, include_date: bool=True, include_created_at: bool=True, color: Optional[str]=None):
+        """ Add a report header to the current page
+
+        Args:
+            include_date (bool): Add the current date to the report
+            include_created_at (bool): Include a subheader with the exact creation time of the report
+            color (Optional[str]): The backgroound color for the header
+        """
+        self.current.add_report_header(self.report_title, self.report_date, include_date, include_created_at, color)
+
+    def add_error_warning_info_section(self, **kwargs):
+        """ Add a section detailing errors, warnings, and info """
+        self.current.add_error_warning_info_section(**kwargs)
+
+    def add_header(self, header_text: str, color: Optional[str]=None):
+        """ Add a header to the current page
+
+        Args:
+            header_text (str): Header text. You can use any valid HTML code inside the text, e.g., links and such.
+            color (Optional[str]): Color of the header box
+        """
+        self.current.add_header(header_text, color)
+
+    def add_sub_header(self, header_text: str, color: Optional[str]=None, sub_level: Optional[int]=None):
+        """ Add a sub header to the current page
+
+        Args:
+            header_text (str): Header text. You can use any valid HTML code inside the text, e.g., links and such.
+            color (Optional[str]): Color of the header box
+            sub_level (Optional[int]): Shrinks the width of the header box. Levels can be 1 to 5. The higher the level
+                the smaller the box
+        """
+        self.current.add_sub_header(header_text, color, sub_level)
+
+    # Miscellaneous elements
+    # ----------------------
+    def add_text(self, text: str, color: Optional[str]=None, align: Optional[Literal['left', 'center', 'right']]=None):
+        """ Add (colored) text to the page
+
+        This will create a new paragraph. So if you want to mix colors within
+        one paragraph you'll have to do this yourself for now
+
+        Args:
+            text (str): Your text
+            color (Optional[str]): One of the supported colors
+            align (Optional[Literal['left', 'center', 'right']]): Alignment of text
+        """
+        self.current.add_text(text, color, align)
+
+    def add_table(
+            self,
+            table_data: Union[DataFrame, list[list[Any]]],
+            formatters: Optional[Union[str, Callable, list[str], list[Callable]]]=None,
+            options: Optional[list[str]]=None,
+            size: Optional[int]=None,
+            align: Optional[Literal['left','center','right']]=None,
+            caption: Optional[str]=None,
+            footers: Optional[list[list[Any]]]=None,
+            order: Optional[list[list[Any]]]=None,
+            color: Optional[str]=None,
+        ):
+        """ Add a table to the page.
+
+        ``table_data`` can either be a pandas ``DataFrame`` or a list of lists.
+        For the former we assume indices and column labels are already properly
+        formatted. For the latter we assume the first item contains the headers.
+
+        Args:
+            table_data (Union[DataFrame, list[list[Any]]]):
+                Data to tabelize.
+
+            formatters (Optional[Union[str, Callable, list[str], list[Callable]]]):
+                Formatters applied to each table element. If a list is provided it
+                must match the number of columns. A single formatter is applied
+                to all columns. The default formatter is ``str()``.
+
+            options (Optional[list[str]]):
+                Turn optional elements of the DataTable on. Supported options:
+
+                - ``page`` - Split long tables into pages of 10 (configurable)
+                - ``info`` - Show number of rows
+                - ``search`` - Add a search field
+                - ``no_sort`` - Disable initial sorting
+                - ``color_negative_values`` - Highlight values < 0 in red
+                - ``color_positive_values`` - Highlight values > 0 in green
+                - ``full_width`` - Table spans full window width
+
+            size (Optional[int]):
+                Sets the width of the table (1-12). ``12`` uses full container width.
+
+            align (Optional[str]):
+                Alignment of cell content.
+
+            caption (Optional[str]):
+                Text shown below the table.
+
+            footers (Optional[list[list[Any]]]):
+                Rows always shown at the bottom of the table.
+
+            order (Optional[list[list[Any]]]):
+                Default table order in the form ``[[col_idx, 'asc' | 'desc'], ...]``.
+
+            color (Optional[str]):
+                Text color. Automatically determined if omitted.
+        """
+        self.current.add_table(table_data, formatters, options, size, align, caption, footers, order, color)
+
+    def add_list(self, list_items: list[str]):
+        """ Add a list to the current page
+
+        Args:
+            list_items (list[str]): A list to be added to the page
+        """
+        self.current.add_list(list_items)
+
+    def add_image(self,
+            image_source: Union[str, Path],
+            remove_source: Optional[bool]=None,
+            responsive: Optional[bool]=None,
+            center: Optional[bool]=None,
+        ):
+        """ Add an image to the current page
+
+        Args:
+            image_source (Union[str, Path]): The path to the image to add
+            remove_source (Optional[bool]): If true the source will be deleted and only acopy in the report dir is kept
+            responsive (Optional[bool]): If true the image will automatically be resized to match the outer container
+            center (Optional[bool]): If true the image will be centered
+        """
+        self.current.add_image(image_source, remove_source, responsive, center)
+
+    def add_local_link_to_page(self, page_name: str, link_name: str):
+        """ Add a link to another page to the current page
+
+        Args:
+            page_name (str): The key/name of the page to link to
+            link_name (str): The text that will be displayed
+        """
+        link = self.get_local_link_to_page(page_name, link_name)
+        self.current.add_local_link(link)
+
+    def get_local_link_to_page(self, page_name: str, link_name: str):
+        """ Get a link to another page to the current page
+
+        Args:
+            page_name (str): The key/name of the page to link to
+            link_name (str): The text that will be displayed
+        """
+        return self.pages[page_name].get_link_to_page(link_name)
+
+    def add_global_link_to_page(self, page_name: str, link_name: str):
+        """ Add a link to another page to the navbar
+
+        Args:
+            page_name (str): The key/name of the page to link to
+            link_name (str): The text that will be displayed
+        """
+        link = self.pages[page_name].get_link_to_page(link_name, for_navbar=True)
+        self.global_links.append(link)
+
+    def get_link_to_page(self, **kwargs):
+        """ Get a link to the current page """
+        self.current.get_link_to_page(**kwargs)
+
+    def add_custom_html_code(self, html: str):
+        """ Add custom / generic html code
+
+        Args:
+            html (str): The HTML string.
+        """
+        self.current.add_custom_html_code(html)
+
+    # Layouting
+    # ---------
+    def open_columns(self):
+        """ Start a column layout """
+        self.current.open_columns()
+
+    def add_column(self):
+        """ Add another column to the current column layout """
+        self.current.add_column()
+
+    def close_columns(self):
+        """ Close the current column layout """
+        self.current.close_columns()
+
+    def open_tabs(self):
+        """ Open a tab layout"""
+        self.current.open_tabs()
+
+    def add_tab(self, name: str):
+        """ Add another tab to the current tab layout
+
+        Args:
+            name (str): The text shown on the tab
+        """
+        self.current.add_tab(name)
+
+    def close_tabs(self):
+        """ Close the current tab layout"""
+        self.current.close_tabs()
+
+    def open_navbar(self, **kwargs):
+        """ Open a navbar layout """
+        self.current.open_navbar(**kwargs)
+
+    def add_navbar_item(self, name: str):
+        """ Add another navbar item to the current navbar layout
+
+        Args:
+            name (str): The text shown on the navbar pill
+        """
+        self.current.add_navbar_item(name)
+
+    def close_navbar(self):
+        """ Close the current navbar layout """
+        self.current.close_navbar()
+
+    def open_accordion(self, **kwargs):
+        """ Open a accordion layout"""
+        self.current.open_accordion(**kwargs)
+
+    def add_accordion_item(self, name: str):
+        """ Add another accordion item to the current accordion layout
+
+        Args:
+            name (str): The text shown on the accordion
+        """
+        self.current.add_accordion_item(name)
+
+    def close_accordion(self):
+        """ Close  the current accorion layout """
+        self.current.close_accordion()
+
+    def open_sublevel(self, **kwargs):
+        """ Open a sub-level layout """
+        self.current.open_sublevel(**kwargs)
+
+    def close_sublevel(self):
+        """ Close the current sub-level layout """
+        self.current.close_sublevel()

basic_report/templates/accordion.css

@@ -0,0 +1,20 @@
+.accordion .card {
+  background-color: {{ accordion_body_background_color }};
+  border: {{ accordion_border_size }} solid {{ accordion_border_color }};
+}
+
+/* Remove default header bottom border */
+.accordion .card-header {
+  background-color: {{ accordion_header_background_color }};
+  border-bottom: none;
+}
+
+/* Control the border between header and body */
+.accordion .card-body {
+  border-top: {{ accordion_body_top_border_size }} solid {{ accordion_body_top_border_color }};   /* ← your desired color */
+  color: {{ accordion_body_font_color }};
+}
+
+.accordion .btn-link {
+  color: {{ accordion_link_color }};
+}

basic_report/templates/accordion.html

@@ -0,0 +1,20 @@
+<div class="container p-1">
+  <div class="accordion" id="{{ accordion_id }}">
+  {% for item in accordion_items %}
+    <div class="card">
+      <div class="card-header">
+        <h5 class="mb-0">
+          <button class="btn btn-link collapsed w-100" type="button" data-toggle="collapse" data-target="#{{ item[1] }}">
+            {{ item[0] }}
+          </button>
+        </h5>
+      </div>
+      <div id="{{ item[1] }}" class="collapse" data-parent="#{{ accordion_id }}">
+        <div class="card-body">
+          {{ item[2] }}
+        </div>
+      </div>
+    </div>
+  {% endfor %}
+  </div>
+</div>

basic_report/templates/base.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+<head>
+<!-- META TAGS --!>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+
+<!-- BOOTSTRAP --!>
+<link rel="stylesheet" href="css_and_scripts/bootstrap.min.css">
+
+<!-- BOOTSTRAP - OPTIONAL JavaScript --!>
+<script src="css_and_scripts/jquery-3.3.1.slim.min.js"></script>
+<script src="css_and_scripts/popper.min.js"></script>
+<script src="css_and_scripts/bootstrap.min.js"></script>
+
+<!-- DATATABLES --!>
+<script src="css_and_scripts/jquery.dataTables.min.js"></script>
+<script src="css_and_scripts/dataTables.bootstrap4.min.js"></script>
+
+<link rel="stylesheet" type="text/css" href="css_and_scripts/custom_colors.css" />
+<link rel="stylesheet" type="text/css" href="css_and_scripts/tabs.css" />
+<link rel="stylesheet" type="text/css" href="css_and_scripts/site.css" />
+<link rel="stylesheet" type="text/css" href="css_and_scripts/accordion.css" />
+<link rel="stylesheet" type="text/css" href="css_and_scripts/table.css" />
+<link rel="stylesheet" type="text/css" href="css_and_scripts/navbar.css" />
+
+{{ head_content }}
+
+</head>
+
+ <style>
+/* BOOTSTRAP HACK: fix content width inside hidden tabs */
+.tab-content > .tab-pane:not(.active),
+.pill-content > .pill-pane:not(.active) {
+    display: block;
+    height: 0;
+    overflow-y: hidden;
+    } 
+
+/* TABLE classes to highlight positive (negative) numbers in green (red) */
+.positive {
+    color: #28a745bf;
+}
+
+.negative {
+    color: #dc3545bf;
+}
+
+/* TABLE class to separate footer from the rest of the table */
+.double-top-border {
+    border-top: 3px double #c5c9c7;
+}
+
+</style>
+
+<body>
+{{ body_content }}
+</body>
+</html>

basic_report/templates/colors.css

@@ -0,0 +1,30 @@
+{% for color in color_items %}
+/*------------------------------------
+COLOR {{ color.name }}
+------------------------------------*/
+.alert-{{ color.name }} {
+  color: {{ color.face_color }};
+  background-color: {{ color.font_and_background }};
+  {%- if color_mode == 'light' %}
+  border-color: {{ color.border_light }};
+  {%- else %}
+  border-color: {{ color.border_dark }};
+  {%- endif %}
+  border-width: 1px;
+}
+
+.alert-{{ color.name }} a {
+  color: {{ color.link }};
+  text-decoration: underline;
+  font-weight: 600;
+}
+
+.alert-{{ color.name }} a:hover {
+  color: {{ color.hover }};
+  text-decoration-thickness: 2px;
+}
+
+.text-{{ color.name }} {
+  color: {{ color.font_and_background }}
+}
+{% endfor %}

basic_report/templates/columns.html

@@ -0,0 +1,9 @@
+<div class="container p-1">
+  <div class="row">
+  {% for item in column_items %}
+    <div class="col">
+      {{ item[0] }}
+    </div>
+  {% endfor %}
+  </div>
+</div>

basic_report/templates/global_links.html

@@ -0,0 +1,7 @@
+<nav class="navbar sticky-top navbar-dark bg-dark navbar-expand-lg">
+  <ul class="navbar-nav">
+  {% for item in links %}
+    <li class="nav-item">{{ item }}</li>
+  {% endfor %}
+  </ul>
+</nav>

basic_report/templates/header.html

@@ -0,0 +1,5 @@
+<div class="container p-1 justify-content-center">
+  <div class="alert alert-{{ header_color }} text-center shadow-sm" role="alert">
+    <strong>{{ header_text }}</strong>
+  </div>
+</div>

basic_report/templates/image.html

@@ -0,0 +1,16 @@
+<div class="container p-1">
+  {% if center %}
+    <center>
+  {% endif %}
+  <a href="{{ source }}">
+  {% if responsive %}
+    <img src="{{ source }}" class="img-fluid">
+  {% else %}
+    <img src="{{ source }}">
+  {% endif %}
+  </a>
+  {% if center %}
+    </center>
+  {% endif %}
+</div>
+

basic_report/templates/list.html

@@ -0,0 +1,7 @@
+<div class="container">
+  <ul>
+    {% for item in list_items %}
+      <li>{{ item }}</li>
+    {% endfor %}
+  </ul>
+</div>

basic_report/templates/navbar.css

@@ -0,0 +1,17 @@
+{% for color in color_items %}
+/*------------------------------------
+COLOR {{ color.name }}
+------------------------------------*/
+.nav-pills .pill-{{ color.name }} .nav-link:not(.active) {
+    background-color: {{ color.font_and_background }}51;
+    color: {{ color.font_and_background }};
+    font-weight: normal;
+}
+
+
+.nav-pills .pill-{{ color.name }} .nav-link {
+    background-color: {{ color.font_and_background }}bf;
+    color: {{ color.face_color }};
+    font-weight: bolder;
+}
+{% endfor %}

basic_report/templates/navbar_left.html

@@ -0,0 +1,32 @@
+<div class="container p-2">
+  <div class="row">
+    <div class="col-2">
+      <ul class="nav nav-pills nav-stacked nav-fill" role="tablist">
+        {% for item in navbar_items %}
+          <li class="nav-item p-1 pill-{{ color }}">
+          {% if loop.index == 1 %}
+            <a class="nav-link active" data-toggle="pill" href="#{{ item[1] }}" role="tab">{{ item[0] }}</a>
+          {% else %}
+            <a class="nav-link" data-toggle="pill" href="#{{ item[1] }}" role="tab">{{ item[0] }}</a>
+          {% endif %}
+          </li>
+        {% endfor %}
+      </ul>
+    </div>
+    <div class = "col-10">    
+      <div class="tab-content">
+        {% for item in navbar_items %}
+          {% if loop.index == 1 %}
+            <div class="tab-pane fade show active" id="{{ item[1] }}">
+          {% else %}
+            <div class="tab-pane fade" id="{{ item[1] }}">
+          {% endif %}
+          <div class="container">
+            {{ item[2] }}
+          </div>
+        </div>
+        {% endfor %}
+      </div>
+    </div>
+  </div>
+</div>

basic_report/templates/navbar_right.html

@@ -0,0 +1,32 @@
+<div class="container p-2">
+  <div class="row">
+    <div class = "col-10">    
+      <div class="tab-content">
+        {% for item in navbar_items %}
+          {% if loop.index == 1 %}
+            <div class="tab-pane fade show active" id="{{ item[1] }}">
+          {% else %}
+            <div class="tab-pane fade" id="{{ item[1] }}">
+          {% endif %}
+          <div class="container">
+            {{ item[2] }}
+          </div>
+        </div>
+        {% endfor %}
+      </div>
+    </div>
+    <div class="col-2">
+      <ul class="nav nav-pills nav-stacked nav-fill" role="tablist">
+        {% for item in navbar_items %}
+          <li class="nav-item p-1 pill-{{ color }}">
+          {% if loop.index == 1 %}
+            <a class="nav-link active" data-toggle="pill" href="#{{ item[1] }}" role="tab">{{ item[0] }}</a>
+          {% else %}
+            <a class="nav-link" data-toggle="pill" href="#{{ item[1] }}" role="tab">{{ item[0] }}</a>
+          {% endif %}
+          </li>
+        {% endfor %}
+      </ul>
+    </div>
+  </div>
+</div>