gov-uk-dashboards 16.1.0__tar.gz → 17.0.0__tar.gz

{gov_uk_dashboards-16.1.0/gov_uk_dashboards.egg-info → gov_uk_dashboards-17.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gov_uk_dashboards
-Version: 16.1.0
+Version: 17.0.0
 Summary: Provides access to functionality common to creating a data dashboard.
 Author: Department for Levelling Up, Housing and Communities
 Description-Content-Type: text/markdown

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/gov_uk_dashboards/components/dash/__init__.py

@@ -68,7 +68,6 @@ from .card import card, empty_card
 from .card_full_width import card_full_width
 from .apply_and_reset_filters_buttons import apply_and_reset_filters_buttons
 from .download_button import download_button
-from .download_button import download_button_with_icon
 from .collapsible_panel import collapsible_panel
 from .dashboard_container import dashboard_container
 from .details import details

gov_uk_dashboards-17.0.0/gov_uk_dashboards/components/dash/download_button.py

@@ -0,0 +1,66 @@
+"""download_button"""
+import warnings
+from dash import html
+
+from gov_uk_dashboards.constants import DOWNLOAD_BUTTON_CLASSES
+
+
+def download_button(button_text: str, button_id: str = "download-button"):
+    """
+    Return a download button which is aligned to the right
+
+    Args:
+    button_text (str): The text to display on the button.
+    button_id: (str, Optional) = id for dropdown, default to "download-button"
+    """
+    warnings.warn(
+        "Note there is an alternative function to download_button() called "
+        "create_download_button_with_icon() which includes a download icon and improved styling.",
+        Warning,
+        stacklevel=2,
+    )
+
+    return html.Div(
+        [
+            html.Button(
+                button_text,
+                id=button_id,
+                n_clicks=0,
+                className="govuk-button govuk-button--secondary",
+            ),
+        ],
+        className="govuk-button-group",
+        style={"float": "right"},
+    )
+
+
+def create_download_button_with_icon(
+    button_text: str, button_id_name: str
+) -> html.Button:
+    """Create a download button with icon, aligned to the left.
+
+    Parameters:
+    - button_id_name (str): A unique identifier for the button.
+
+    Returns:
+    - html.Button: Download button.
+    """
+    download_type = button_text.lower().replace(" ", "-")
+    return html.Button(
+        [
+            html.Div("", className="download-icon"),
+            button_text,
+        ],
+        id={
+            "download-type": download_type,
+            "name": button_id_name,
+        },
+        n_clicks=0,
+        className=DOWNLOAD_BUTTON_CLASSES,
+        type="submit",
+        style={
+            "display": "flex",
+            "alignItems": "center",
+            "gap": "8px",
+        },
+    )

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/gov_uk_dashboards/components/helpers/display_chart_or_table_with_header.py

@@ -3,11 +3,8 @@
 from dash import html
 from dash.development.base_component import Component
 
-from gov_uk_dashboards.components.dash.create_download_chart_button import (
-    create_download_chart_button,
-)
-from gov_uk_dashboards.components.dash.create_download_data_button import (
-    create_download_data_button,
+from gov_uk_dashboards.components.dash.download_button import (
+    create_download_button_with_icon,
 )
 from gov_uk_dashboards.components.dash.heading import HeadingSizes
 
@@ -36,11 +33,6 @@ def display_chart_or_table_with_header(
         [
             html.Div(
                 [
-                    (
-                        create_download_chart_button(button_id_name=download_button_id)
-                        if download_button_id
-                        else None
-                    ),
                     html.Div(
                         [
                             html.H2(
@@ -61,20 +53,23 @@ def display_chart_or_table_with_header(
             html.Div(
                 (
                     [
-                        html.H3(
-                            "Download this data",
-                            className=HeadingSizes.SMALL,
-                            style={
-                                **{"color": "black", "margin": "0px 0px 5px"},
-                                **{"padding-top": "20px"},
-                            },
-                        ),
-                        create_download_data_button(
-                            button_id_name=download_data_button_id
+                        html.Div(
+                            [
+                                create_download_button_with_icon(
+                                    "Download chart", download_button_id
+                                )
+                                if download_button_id
+                                else [],
+                                create_download_button_with_icon(
+                                    "Download data", download_data_button_id
+                                )
+                                if download_data_button_id
+                                else [],
+                            ],
+                            className="govuk-button-group",
+                            style={"padding-top": "20px"},
                         ),
                     ]
-                    if download_data_button_id
-                    else []
                 ),
             ),
         ],

gov_uk_dashboards-17.0.0/gov_uk_dashboards/components/helpers/get_chart_for_download.py

@@ -0,0 +1,21 @@
+"""get_chart_for_download"""
+from gov_uk_dashboards.constants import MAIN_TITLE, SUBTITLE
+
+
+def get_chart_for_download(self, fig):
+    """Returns a fig with title and subtitle for download as png"""
+    main_title = self.title_data[MAIN_TITLE]
+    subtitle = self.title_data[SUBTITLE]
+
+    fig.update_layout(
+        title={
+            "text": f"<b><span style='color: black; margin: 0px 0px 5px'>{main_title}</span></b>",
+            "x": 0.01,
+            "xanchor": "left",
+        },
+        title_subtitle={
+            "text": f"<b><span style='color: black; margin: 0px 0px 5px'>{subtitle}</span></b>"
+        },
+        margin={"t": 100},
+    )
+    return fig

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/gov_uk_dashboards/components/plotly/stacked_barchart.py

@@ -7,6 +7,9 @@ import polars as pl
 
 import plotly.graph_objects as go
 
+from gov_uk_dashboards.components.helpers.get_chart_for_download import (
+    get_chart_for_download,
+)
 from gov_uk_dashboards.constants import (
     CHART_LABEL_FONT_SIZE,
     CUSTOM_DATA,
@@ -117,6 +120,10 @@ class StackedBarChart:
             self.download_data_button_id,
         )
 
+    def get_stacked_bar_chart_for_download(self):
+        """Return fig with title and subtitle for download as png"""
+        return get_chart_for_download(self, self.create_stacked_bar_chart())
+
     def create_stacked_bar_chart(
         self,
     ):

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/gov_uk_dashboards/components/plotly/time_series_chart.py

@@ -30,6 +30,9 @@ from gov_uk_dashboards.components.helpers.plotting_helper_functions import (
     get_legend_configuration,
     get_rgba_from_hex_colour_and_alpha,
 )
+from gov_uk_dashboards.components.helpers.get_chart_for_download import (
+    get_chart_for_download,
+)
 from gov_uk_dashboards.components.helpers.update_layout_bgcolor_margin import (
     update_layout_bgcolor_margin,
 )
@@ -129,6 +132,10 @@ class TimeSeriesChart:
             self.download_data_button_id,
         )
 
+    def get_time_series_chart_for_download(self):
+        """Return fig with title and subtitle for download as png"""
+        return get_chart_for_download(self, self.create_time_series_chart())
+
     def create_time_series_chart(
         self,
     ):
@@ -156,6 +163,7 @@ class TimeSeriesChart:
                 line={"color": line_color},
                 hoverinfo="skip",  # 👈 This line disables hover for this trace
                 showlegend=False,  # Optional: hide it from legend too
+                legendgroup=self.additional_line["legend_group"],
             )
             fig.add_trace(trace_connector)
         # pylint: disable=unused-variable
@@ -173,12 +181,14 @@ class TimeSeriesChart:
                 marker_sizes = [0] + [12] * (len(df.with_row_count()) - 1)
             else:
                 marker_sizes = [12] * (len(df.with_row_count()))
+            legendgroup = self._get_legend_group(df)
             fig.add_trace(
                 self.create_time_series_trace(
                     df.sort(self.x_axis_column),
                     trace_name,
                     line_style={"dash": "solid", "color": colour},
                     marker={"symbol": marker, "size": marker_sizes, "opacity": 1},
+                    legendgroup=legendgroup,
                 ),
             )
 
@@ -220,6 +230,7 @@ class TimeSeriesChart:
             ]
 
             hover_text_full = hover_text + hover_text[::-1]
+            legendgroup = self._get_legend_group(fill_df)
             fig.add_trace(
                 go.Scatter(
                     x=x_series + x_series[::-1],
@@ -232,6 +243,7 @@ class TimeSeriesChart:
                     name=self.filled_traces_dict["name"] + LEGEND_SPACING,
                     hovertemplate=hover_text_full,
                     hoveron="points",
+                    legendgroup=legendgroup,
                 )
             )
         self._format_x_axis(fig)
@@ -299,6 +311,14 @@ class TimeSeriesChart:
         )
         return fig
 
+    def _get_legend_group(self, df):
+        if "legend_group" in df.columns and len(df) > 0:
+            value = df["legend_group"][0]
+            legendgroup = value if value is not None else None
+        else:
+            legendgroup = None
+        return legendgroup
+
     # pylint: disable=duplicate-code
     def _format_x_axis(self, fig):
         tick_text, tick_values, range_x = self._get_x_axis_content()
@@ -317,6 +337,7 @@ class TimeSeriesChart:
         trace_name: str,
         line_style: dict[str, str],
         marker: dict[str, str],
+        legendgroup: str,
     ):
         """Creates a trace for the plot.
 
@@ -326,6 +347,7 @@ class TimeSeriesChart:
             trace_name (str): Name of trace.
             line_style (dict[str, str]): Properties for line_style parameter.
             marker (dict[str,str]): Properties for marker parameter.
+            legendgroup (str): Name to group by in legend,
         """
         return go.Scatter(
             x=df[self.x_axis_column],
@@ -339,6 +361,7 @@ class TimeSeriesChart:
             showlegend=(
                 trace_name in self.legend_dict if self.legend_dict is not None else True
             ),
+            legendgroup=legendgroup,
         )
 
     def _get_hover_template(self, df, trace_name):

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/gov_uk_dashboards/constants.py

@@ -18,3 +18,9 @@ UNIT_SIZE = "Unit size"
 DEFAULT_COLOURSCALE = "tealgrn"
 
 LEGEND_SPACING = "\u00A0" * 5
+
+DOWNLOAD_BUTTON_CLASSES = (
+    "govuk-button govuk-button--primary "
+    "govuk-!-margin-bottom-0 govuk-!-margin-top-4 "
+    "flex w-auto items-center gap-2 print:hidden"
+)

gov_uk_dashboards-17.0.0/gov_uk_dashboards/lib/download_functions/convert_fig_to_image_and_download.py

@@ -0,0 +1,16 @@
+"""convert_fig_to_image_and_download"""
+
+import plotly.graph_objects as go
+import plotly.io as pio
+from dash import dcc
+
+
+def convert_fig_to_image_and_download(fig: go.Figure, name: str):
+    """Converts a given Plotly figure to a PNG image and returns a Dash component
+    for downloading the image.
+    """
+    fig.update_layout(margin={"t": 150, "b": 100, "l": 100, "r": 50})
+
+    filename = f"{name}-chart.png"
+    img_bytes = pio.to_image(fig, format="png", width=1600, height=800)
+    return dcc.send_bytes(img_bytes, filename)

gov_uk_dashboards-17.0.0/gov_uk_dashboards/lib/download_functions/download_csv_with_headers.py

@@ -0,0 +1,114 @@
+"""download_csv_with_headers"""
+import io
+import polars as pl
+from dash import dcc
+from gov_uk_dashboards.lib.datetime_functions.datetime_functions import (
+    get_todays_date_for_downloaded_csv,
+)
+
+
+def download_csv_with_headers(
+    list_of_df_title_subtitle_dicts: list[dict[str, str]],
+    name: str,
+    sensitivity_label: str,
+    additional_text: list[str] = None,
+):  # pylint: disable=too-many-locals
+    """Adds a header above multiple dataframes,
+    separates them with blank rows, and downloads as CSV.
+
+    Args:
+        list_of_df_title_subtitle_dicts (list[dict[]]): List of dictionaries containing keys: "df",
+        "title" and "subtitle"
+        name (str): Filename for CSV.
+        sensitivity_label (str): Sensitivity label. Str or None.
+        additional_text (list[str]): Additional text to inlcude in headers after data downloaded.
+            Str or None.
+    """
+
+    csv_buffer = io.StringIO()
+
+    column_list = list(list_of_df_title_subtitle_dicts[0]["df"].columns)
+    column_dict = {column_name: column_name for column_name in column_list}
+    blank_dict = {
+        f"{i}": None
+        for i in range(
+            _get_number_of_max_columns_from_all_dfs(list_of_df_title_subtitle_dicts)
+            - len(column_list)
+        )
+    }  # range is missing columns in first df compared to max columns across all dfs
+
+    subtitle = list_of_df_title_subtitle_dicts[0]["subtitle"]
+
+    header_data = [
+        {column_list[0]: "Date downloaded: " + get_todays_date_for_downloaded_csv()},
+        *(
+            [{column_list[0]: text} for text in additional_text]
+            + [{column_list[0]: None}]
+            if additional_text is not None
+            else []
+        ),
+        {column_list[0]: list_of_df_title_subtitle_dicts[0]["title"]},
+        *(
+            [{column_list[0]: subtitle}] if subtitle is not None else []
+        ),  # Uses unpacking (*) to add the subtitle row if subtitle is not None. If subtitle is
+        # None, it unpacks an empty list, effectively skipping the row.
+        {column_list[0]: None},  # Blank row
+        {**column_dict, **blank_dict},
+    ]
+
+    if sensitivity_label:
+        header_data = [{column_list[0]: sensitivity_label}] + header_data
+
+    pl.DataFrame(header_data).write_csv(csv_buffer, include_header=False)
+
+    for i, data in enumerate(list_of_df_title_subtitle_dicts):
+        df = data["df"]
+        title = data["title"]
+        subtitle = data["subtitle"]
+
+        if i > 0 and title is not None:
+            column_dict = {column_name: column_name for column_name in list(df.columns)}
+            header_data = [
+                {column_list[0]: title},
+                *(
+                    [{column_list[0]: subtitle}] if subtitle is not None else []
+                ),  # Uses unpacking (*) to add the subtitle row if subtitle is not None. If
+                # subtitle is None, it unpacks an empty list, effectively skipping the row.
+                {column_list[0]: None},  # Blank row
+            ]
+            pl.DataFrame(header_data).write_csv(csv_buffer, include_header=False)
+        df.write_csv(csv_buffer, include_header=i > 0)
+
+        if i < len(list_of_df_title_subtitle_dicts) - 1:
+            blank_row = pl.DataFrame({df.columns[0]: [None]})
+            blank_row.write_csv(csv_buffer, include_header=False)
+
+    csv_buffer.seek(0)
+    csv_data = (
+        "\ufeff" + csv_buffer.getvalue()
+    )  # Adding \ufeff ensures the correct character encoding is detected for £
+
+    return dcc.send_string(csv_data, f"{name}.csv")
+
+
+def _get_number_of_max_columns_from_all_dfs(list_of_df_title_subtitle_dicts):
+    max_columns = 0
+    index_of_max_cols = -1
+
+    for idx, dic in enumerate(list_of_df_title_subtitle_dicts):
+        # Get the DataFrame
+        df = dic["df"]
+
+        # Get the number of columns
+        num_columns = df.shape[1]
+
+        # Update if this DataFrame has more columns
+        if num_columns > max_columns:
+            max_columns = num_columns
+            index_of_max_cols = idx
+
+    max_columns = len(
+        list(list_of_df_title_subtitle_dicts[index_of_max_cols]["df"].columns)
+    )
+
+    return max_columns

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0/gov_uk_dashboards.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gov_uk_dashboards
-Version: 16.1.0
+Version: 17.0.0
 Summary: Provides access to functionality common to creating a data dashboard.
 Author: Department for Levelling Up, Housing and Communities
 Description-Content-Type: text/markdown

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/gov_uk_dashboards.egg-info/SOURCES.txt

@@ -51,8 +51,6 @@ gov_uk_dashboards/components/dash/card_full_width.py
 gov_uk_dashboards/components/dash/collapsible_panel.py
 gov_uk_dashboards/components/dash/comparison_la_filter_button.py
 gov_uk_dashboards/components/dash/context_banner.py
-gov_uk_dashboards/components/dash/create_download_chart_button.py
-gov_uk_dashboards/components/dash/create_download_data_button.py
 gov_uk_dashboards/components/dash/dashboard_container.py
 gov_uk_dashboards/components/dash/details.py
 gov_uk_dashboards/components/dash/download_button.py
@@ -81,6 +79,7 @@ gov_uk_dashboards/components/dash/warning_text.py
 gov_uk_dashboards/components/helpers/__init__.py
 gov_uk_dashboards/components/helpers/display_chart_or_table_with_header.py
 gov_uk_dashboards/components/helpers/generate_dash_graph_from_figure.py
+gov_uk_dashboards/components/helpers/get_chart_for_download.py
 gov_uk_dashboards/components/helpers/plotting_helper_functions.py
 gov_uk_dashboards/components/helpers/update_layout_bgcolor_margin.py
 gov_uk_dashboards/components/plotly/__init__.py
@@ -108,4 +107,7 @@ gov_uk_dashboards/lib/dap/__init__.py
 gov_uk_dashboards/lib/dap/dap_deployment.py
 gov_uk_dashboards/lib/dap/get_dataframe_from_cds.py
 gov_uk_dashboards/lib/datetime_functions/__init__.py
-gov_uk_dashboards/lib/datetime_functions/datetime_functions.py
+gov_uk_dashboards/lib/datetime_functions/datetime_functions.py
+gov_uk_dashboards/lib/download_functions/__init__.py
+gov_uk_dashboards/lib/download_functions/convert_fig_to_image_and_download.py
+gov_uk_dashboards/lib/download_functions/download_csv_with_headers.py

{gov_uk_dashboards-16.1.0 → gov_uk_dashboards-17.0.0}/setup.py

@@ -10,7 +10,7 @@ setup(
     author="Department for Levelling Up, Housing and Communities",
     description="Provides access to functionality common to creating a data dashboard.",
     name="gov_uk_dashboards",
-    version="16.1.0",
+    version="17.0.0",
     long_description=long_description,
     long_description_content_type="text/markdown",
     packages=find_packages(),

gov_uk_dashboards-16.1.0/gov_uk_dashboards/components/dash/create_download_chart_button.py

@@ -1,25 +0,0 @@
-"""create_download_chart_button"""
-
-from dash import html
-from gov_uk_dashboards.components.dash import download_button_with_icon
-
-
-def create_download_chart_button(button_id_name: str) -> html.Div:
-    """Create a download button for charts, aligned to the right.
-
-    Parameters:
-    - button_id_name (str): A unique identifier for the button.
-
-    Returns:
-    - html.Div: A Div element containing a download button.
-    """
-    return html.Div(
-        download_button_with_icon(
-            button_text="Download chart",
-            button_id={
-                "download-type": "download-chart",
-                "name": button_id_name,
-            },
-        ),
-        style={"textAlign": "right"},
-    )

gov_uk_dashboards-16.1.0/gov_uk_dashboards/components/dash/create_download_data_button.py

@@ -1,25 +0,0 @@
-"""create_download_data_button"""
-
-from dash import html
-from gov_uk_dashboards.components.dash import download_button_with_icon
-
-
-def create_download_data_button(button_id_name: str) -> html.Div:
-    """Create a download button for data, aligned to the right.
-
-    Parameters:
-    - button_id_name (str): A unique identifier for the button.
-
-    Returns:
-    - html.Div: A Div element containing a download button.
-    """
-    return html.Div(
-        download_button_with_icon(
-            button_text=".csv",
-            button_id={
-                "download-type": "download-data",
-                "name": button_id_name,
-            },
-        ),
-        style={"float": "left", "margin-top": "-20px"},
-    )

gov_uk_dashboards-16.1.0/gov_uk_dashboards/components/dash/download_button.py

@@ -1,62 +0,0 @@
-"""download_button"""
-import warnings
-from dash import html
-
-
-def download_button(button_text: str, button_id: str = "download-button"):
-    """
-    Return a download button which is aligned to the right
-
-    Args:
-    button_text (str): The text to display on the button.
-    button_id: (str, Optional) = id for dropdown, default to "download-button"
-    """
-    warnings.warn(
-        "Note there is an alternative function to download_button() called "
-        "download_button_with_icon() which includes a download icon and improved styling.",
-        Warning,
-        stacklevel=2,
-    )
-
-    return html.Div(
-        [
-            html.Button(
-                button_text,
-                id=button_id,
-                n_clicks=0,
-                className="govuk-button govuk-button--secondary",
-            ),
-        ],
-        className="govuk-button-group",
-        style={"float": "right"},
-    )
-
-
-def download_button_with_icon(button_text: str, button_id: str = "download-button"):
-    """
-    Return a download button styled with additional classes and an SVG icon,
-    aligned to the right.
-
-    Args:
-    button_text (str): The text to display on the button.
-    button_id (str, Optional): ID for the button, defaults to "download-button".
-    """
-    classes = (
-        "govuk-button govuk-button--primary "
-        "govuk-!-margin-bottom-0 govuk-!-margin-top-4 "
-        "flex w-auto items-center gap-2 print:hidden"
-    )
-    return html.Div(
-        [
-            html.Button(
-                [html.Div("", className="download-icon"), button_text],
-                id=button_id,
-                n_clicks=0,
-                className=classes,
-                type="submit",
-                style={"display": "flex", "alignItems": "center", "gap": "8px"},
-            ),
-        ],
-        className="govuk-button-group",
-        style={"float": "right"},
-    )