gov-uk-dashboards 13.5.1__py3-none-any.whl → 14.0.0__py3-none-any.whl

gov_uk_dashboards/components/__init__.py

@@ -4,4 +4,4 @@ using different systems.
 Contains:
 - plotly: Module containing Plotly/Dash components
 """
-from . import plotly
+from . import dash

gov_uk_dashboards/components/dash/__init__.py

@@ -0,0 +1,92 @@
+"""Module containing Dash components for building GOV.UK Design System dashboards.
+
+See: https://design-system.service.gov.uk/components/
+
+Contains:
+- message_banner: Return a changelog banner to be used to communicate to the
+    user when the dashboard was last updated.
+- captioned_figure: Return figure with attached captions that can be read
+    by a screen reader.
+- card: Return a rectangle with a grey background. Mostly used to wrap
+    individual visualisations.
+- card_full_width: Return a card with a grey background that fits the full
+    width of its parent container using CSS flexbox.
+- empty_card: Return an empty card that is hidden to help keep alignment with
+    rows and columns.
+- collapsible_panel: Return a component that allows the user to open and close
+    a collapsible panel containing child components.
+- dashboard_container: Return a HTML wrapper for a whole dashboard.
+- details: Return HTML component for showing a summary expandable with more
+    information beneath.
+- filter_panel: Return a card with a title that allows the user to select and
+    filter metrics on the dashboard.
+- hidden_filter: Return an empty, invisible HTML element that stands in for a
+    filter component.
+- footer: Return a component for a Gov.UK standard footer.
+- graph: Takes a Plotly Figure and returns a responsive Dash graph with useful
+    defaults.
+- heading1: Return a H1 Dash component with gov.uk styling
+- heading2: Return a H1 Dash component with gov.uk styling
+- heading3: Return a H1 Dash component with gov.uk styling
+    - HeadingSizes: Enum of sizes that can be used to manually adjust
+        text size for heading function returns.
+- html_list: Return either a <ul> or <ol> component, with the children set as
+    a list of <li> components matching the list_items provided.
+- key_value_pair: Return an element that displays a value (such as a metric)
+    labelled by a key (such as the name of the metric).
+- main_content: Return wrapper for the main content of the dashboard,
+    containing visualisations.
+- navbar: Return a navigation bar for switching between dashboards.
+    - navbar_link: Return a link for use with the navbar.
+    - navbar_link_active: Return a link that appears highlighted, suggesting to
+        the user that they are already viewing the linked dashboard.
+- side_navbar: Return a navigation bar for switching between dashboards.
+    - side_navbar_link: Return a link for use with the side_navbar.
+    - side_navbar_link_active: Return a link that appears highlighted,
+        suggesting to the user that they are already viewing the linked
+        dashboard.
+- no_data_message: Return a list of strings with a message for when
+    selection does not provide data.
+- paragraph: Return a formatted <p> html component with the children provided.
+    - ParagraphSizes: Enum for use with paragraph to specify the text size.
+- phase_banner_with_feedback: Return a phase banner with a feedback link,
+    which can be specified.
+- row_component: Returns a horizontal row used to contain cards.
+- table_from_dataframe: Return a html table created from a pandas DataFrame.
+- tooltip_title: Return a tooltip component for explaining details.
+- format_visualisation_commentary: Return paragraph styling commentary.
+- format_visualisation_title: Return a default formatted title for a
+    visualisation.
+- apply_and_reset_filters_buttons: Add apply filters and reset filters buttons, whcih are aligned to
+the right
+- add_filter_button: Return a 'Compare to additional authority' button which is aligned to the right
+"""
+
+from .banners import message_banner
+from ..plotly.captioned_figure import captioned_figure
+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
+from .filter_panel import filter_panel, hidden_filter
+from .footer import footer
+from .graph import graph
+from .heading import heading1, heading2, heading3, HeadingSizes
+from .html_list import html_list
+from .key_value_pair import key_value_pair
+from .main_content import main_content
+from .navbar import navbar, navbar_link, navbar_link_active
+from .no_data_message import no_data_message
+from .paragraph import paragraph, ParagraphSizes
+from .phase_banner import phase_banner_with_feedback
+from .row_component import row_component
+from .side_navbar import side_navbar
+from .table import table_from_dataframe
+from .tooltip_title import tooltip_title
+from .visualisation_commentary import format_visualisation_commentary
+from .visualisation_title import format_visualisation_title
+from .comparison_la_filter_button import add_filter_button

gov_uk_dashboards/components/{create_download_chart_button.py → dash/create_download_chart_button.py}

@@ -1,7 +1,7 @@
 """create_download_chart_button"""
 
 from dash import html
-from gov_uk_dashboards.components.plotly import download_button_with_icon
+from gov_uk_dashboards.components.dash import download_button_with_icon
 
 
 def create_download_chart_button(button_id_name: str) -> html.Div:

gov_uk_dashboards/components/{create_download_data_button.py → dash/create_download_data_button.py}

@@ -1,7 +1,7 @@
 """create_download_data_button"""
 
 from dash import html
-from gov_uk_dashboards.components.plotly import download_button_with_icon
+from gov_uk_dashboards.components.dash import download_button_with_icon
 
 
 def create_download_data_button(button_id_name: str) -> html.Div:

gov_uk_dashboards/components/{plotly → dash}/filter_panel.py

@@ -2,7 +2,7 @@
 from typing import Optional
 from dash import html
 
-from gov_uk_dashboards.components.plotly.heading import heading2
+from gov_uk_dashboards.components.dash.heading import heading2
 from .collapsible_panel import collapsible_panel
 from .row_component import row_component
 

gov_uk_dashboards/components/{plotly → dash}/table.py

@@ -2,8 +2,8 @@
 from typing import Optional
 from pandas import DataFrame
 from dash import html, dcc
-from gov_uk_dashboards.components.plotly.card import card
-from gov_uk_dashboards.components.plotly.paragraph import paragraph
+from gov_uk_dashboards.components.dash.card import card
+from gov_uk_dashboards.components.dash.paragraph import paragraph
 
 # from gov_uk_dashboards.components.plotly.row_component import row_component
 

gov_uk_dashboards/components/{display_chart_or_table_with_header.py → helpers/display_chart_or_table_with_header.py}

@@ -2,14 +2,14 @@
 
 from dash import html
 from dash.development.base_component import Component
-from gov_uk_dashboards.components.create_download_chart_button import (
+
+from gov_uk_dashboards.components.dash.create_download_chart_button import (
     create_download_chart_button,
 )
-from gov_uk_dashboards.components.create_download_data_button import (
+from gov_uk_dashboards.components.dash.create_download_data_button import (
     create_download_data_button,
 )
-
-from gov_uk_dashboards.components.plotly.heading import HeadingSizes
+from gov_uk_dashboards.components.dash.heading import HeadingSizes
 
 
 def display_chart_or_table_with_header(

gov_uk_dashboards/{lib → components/helpers}/plotting_helper_functions.py

@@ -1,7 +1,7 @@
 """Helper functions for use to plot charts"""
 
 
-from constants import (
+from gov_uk_dashboards.constants import (
     CHART_LABEL_FONT_SIZE,
 )
 
@@ -27,3 +27,20 @@ def get_legend_configuration(itemclick=True, itemdoubleclick=True):
         "itemclick": "toggle" if itemclick else False,
         "itemdoubleclick": "toggle" if itemdoubleclick else False,
     }
+
+
+def get_rgba_from_hex_colour_and_alpha(hex_code: str, alpha: float = 1.0) -> str:
+    """Get the rgba string corresponding to a hex-code colour and its alpha (opacity)
+
+    Args:
+        hex_code (str): hex code for converting (with #), e.g. "#00FF00"
+        alpha (float, optional): Desired transparency from 0 to 1. Defaults to 1.0.
+
+    Returns:
+        str: rgba string
+    """
+    if hex_code[0] != "#" or len(hex_code) != 7:
+        raise ValueError
+    rgb_colour = tuple(int(hex_code[i : i + 2], 16) for i in (1, 3, 5))
+
+    return f"rgba{rgb_colour + (alpha,)}"

gov_uk_dashboards/components/plotly/__init__.py

@@ -1,92 +0,0 @@
-"""Module containing Plotly/Dash components for building GOV.UK Design System dashboards.
-
-See: https://design-system.service.gov.uk/components/
-
-Contains:
-- message_banner: Return a changelog banner to be used to communicate to the
-    user when the dashboard was last updated.
-- captioned_figure: Return figure with attached captions that can be read
-    by a screen reader.
-- card: Return a rectangle with a grey background. Mostly used to wrap
-    individual visualisations.
-- card_full_width: Return a card with a grey background that fits the full
-    width of its parent container using CSS flexbox.
-- empty_card: Return an empty card that is hidden to help keep alignment with
-    rows and columns.
-- collapsible_panel: Return a component that allows the user to open and close
-    a collapsible panel containing child components.
-- dashboard_container: Return a HTML wrapper for a whole dashboard.
-- details: Return HTML component for showing a summary expandable with more
-    information beneath.
-- filter_panel: Return a card with a title that allows the user to select and
-    filter metrics on the dashboard.
-- hidden_filter: Return an empty, invisible HTML element that stands in for a
-    filter component.
-- footer: Return a component for a Gov.UK standard footer.
-- graph: Takes a Plotly Figure and returns a responsive Dash graph with useful
-    defaults.
-- heading1: Return a H1 Dash component with gov.uk styling
-- heading2: Return a H1 Dash component with gov.uk styling
-- heading3: Return a H1 Dash component with gov.uk styling
-    - HeadingSizes: Enum of sizes that can be used to manually adjust
-        text size for heading function returns.
-- html_list: Return either a <ul> or <ol> component, with the children set as
-    a list of <li> components matching the list_items provided.
-- key_value_pair: Return an element that displays a value (such as a metric)
-    labelled by a key (such as the name of the metric).
-- main_content: Return wrapper for the main content of the dashboard,
-    containing visualisations.
-- navbar: Return a navigation bar for switching between dashboards.
-    - navbar_link: Return a link for use with the navbar.
-    - navbar_link_active: Return a link that appears highlighted, suggesting to
-        the user that they are already viewing the linked dashboard.
-- side_navbar: Return a navigation bar for switching between dashboards.
-    - side_navbar_link: Return a link for use with the side_navbar.
-    - side_navbar_link_active: Return a link that appears highlighted,
-        suggesting to the user that they are already viewing the linked
-        dashboard.
-- no_data_message: Return a list of strings with a message for when
-    selection does not provide data.
-- paragraph: Return a formatted <p> html component with the children provided.
-    - ParagraphSizes: Enum for use with paragraph to specify the text size.
-- phase_banner_with_feedback: Return a phase banner with a feedback link,
-    which can be specified.
-- row_component: Returns a horizontal row used to contain cards.
-- table_from_dataframe: Return a html table created from a pandas DataFrame.
-- tooltip_title: Return a tooltip component for explaining details.
-- format_visualisation_commentary: Return paragraph styling commentary.
-- format_visualisation_title: Return a default formatted title for a
-    visualisation.
-- apply_and_reset_filters_buttons: Add apply filters and reset filters buttons, whcih are aligned to
-the right
-- add_filter_button: Return a 'Compare to additional authority' button which is aligned to the right
-"""
-
-from .banners import message_banner
-from .captioned_figure import captioned_figure
-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
-from .filter_panel import filter_panel, hidden_filter
-from .footer import footer
-from .graph import graph
-from .heading import heading1, heading2, heading3, HeadingSizes
-from .html_list import html_list
-from .key_value_pair import key_value_pair
-from .main_content import main_content
-from .navbar import navbar, navbar_link, navbar_link_active
-from .no_data_message import no_data_message
-from .paragraph import paragraph, ParagraphSizes
-from .phase_banner import phase_banner_with_feedback
-from .row_component import row_component
-from .side_navbar import side_navbar
-from .table import table_from_dataframe
-from .tooltip_title import tooltip_title
-from .visualisation_commentary import format_visualisation_commentary
-from .visualisation_title import format_visualisation_title
-from .comparison_la_filter_button import add_filter_button

gov_uk_dashboards/components/plotly/choropleth_map.py

@@ -4,10 +4,10 @@ import polars as pl
 import plotly.graph_objects as go
 from dash import dcc
 
-from constants import DEFAULT_COLOURSCALE
+from gov_uk_dashboards.constants import DEFAULT_COLOURSCALE
 
 from gov_uk_dashboards import colours
-from gov_uk_dashboards.components.display_chart_or_table_with_header import (
+from gov_uk_dashboards.components.helpers.display_chart_or_table_with_header import (
     display_chart_or_table_with_header,
 )
 

gov_uk_dashboards/components/plotly/enums.py

@@ -0,0 +1,34 @@
+"""Classes to be used for defined enums and type structures"""
+
+from enum import Enum
+from typing import TypedDict
+
+
+class XAxisFormat(Enum):
+    """Enum for date format on x axis"""
+
+    YEAR = "year"
+    MONTH_YEAR = "month_year"
+    FINANCIAL_QUARTER = "financial_quarter"
+
+
+class TitleDataStructure(TypedDict):
+    """A TypedDict representing the structure of title_data"""
+
+    MAIN_TITLE: str
+    SUBTITLE: str
+
+
+class HoverDataStructure(TypedDict):
+    """A TypedDict representing the structure of hover_data"""
+
+    CUSTOM_DATA: list[str]
+    HOVER_TEXT_HEADERS: list[str]
+
+
+class HoverDataByTrace(TypedDict):
+    """A TypedDict representing hover_data organized by tracename"""
+
+    tracename: dict[
+        str, HoverDataStructure
+    ]  # Each tracename maps to a HoverDataStructure

gov_uk_dashboards/components/plotly/stacked_barchart.py

@@ -1,14 +1,13 @@
 """stacked_barchart function"""
 
-from enum import Enum
 import math
-from typing import Optional, TypedDict
+from typing import Optional
 from dash import html
 import polars as pl
 
 import plotly.graph_objects as go
 
-from constants import (
+from gov_uk_dashboards.constants import (
     CHART_LABEL_FONT_SIZE,
     CUSTOM_DATA,
     DATE_VALID,
@@ -20,50 +19,27 @@ from constants import (
     VALUE,
 )
 from gov_uk_dashboards.colours import AFAccessibleColours
-from gov_uk_dashboards.components.display_chart_or_table_with_header import (
+from gov_uk_dashboards.components.helpers.display_chart_or_table_with_header import (
     display_chart_or_table_with_header,
 )
-from gov_uk_dashboards.components.plotly.generate_dash_graph_from_figure import (
+from gov_uk_dashboards.components.helpers.generate_dash_graph_from_figure import (
     generate_dash_graph_from_figure,
 )
-from gov_uk_dashboards.lib.plotting_helper_functions import get_legend_configuration
+from gov_uk_dashboards.components.helpers.plotting_helper_functions import (
+    get_legend_configuration,
+)
+from gov_uk_dashboards.components.plotly.enums import (
+    HoverDataByTrace,
+    TitleDataStructure,
+    XAxisFormat,
+)
 from gov_uk_dashboards.formatting.human_readable import format_as_human_readable
 
-from gov_uk_dashboards.lib.update_layout_bgcolor_margin import (
+from gov_uk_dashboards.components.helpers.update_layout_bgcolor_margin import (
     update_layout_bgcolor_margin,
 )
 
 
-class XAxisFormat(Enum):
-    """Enum for date format on x axis"""
-
-    YEAR = "year"
-    MONTH_YEAR = "month_year"
-    FINANCIAL_QUARTER = "financial_quarter"
-
-
-class TitleDataStructure(TypedDict):
-    """A TypedDict representing the structure of title_data"""
-
-    MAIN_TITLE: str
-    SUBTITLE: str
-
-
-class HoverDataStructure(TypedDict):
-    """A TypedDict representing the structure of hover_data"""
-
-    CUSTOM_DATA: list[str]
-    HOVER_TEXT_HEADERS: list[str]
-
-
-class HoverDataByTrace(TypedDict):
-    """A TypedDict representing hover_data organized by tracename"""
-
-    tracename: dict[
-        str, HoverDataStructure
-    ]  # Each tracename maps to a HoverDataStructure
-
-
 class StackedBarChart:
     """Class for use in generating stacked bar charts."""