gov-uk-dashboards 13.5.2__py3-none-any.whl → 15.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. gov_uk_dashboards/components/__init__.py +1 -1
  2. gov_uk_dashboards/components/dash/__init__.py +92 -0
  3. gov_uk_dashboards/components/{create_download_chart_button.py → dash/create_download_chart_button.py} +1 -1
  4. gov_uk_dashboards/components/{create_download_data_button.py → dash/create_download_data_button.py} +1 -1
  5. gov_uk_dashboards/components/{plotly → dash}/filter_panel.py +1 -1
  6. gov_uk_dashboards/components/{plotly → dash}/table.py +2 -2
  7. gov_uk_dashboards/components/helpers/__init__.py +0 -0
  8. gov_uk_dashboards/components/{display_chart_or_table_with_header.py → helpers/display_chart_or_table_with_header.py} +4 -4
  9. gov_uk_dashboards/{lib → components/helpers}/plotting_helper_functions.py +17 -0
  10. gov_uk_dashboards/components/plotly/__init__.py +0 -92
  11. gov_uk_dashboards/components/plotly/choropleth_map.py +1 -1
  12. gov_uk_dashboards/components/plotly/enums.py +34 -0
  13. gov_uk_dashboards/components/plotly/stacked_barchart.py +12 -36
  14. gov_uk_dashboards/components/plotly/time_series_chart.py +477 -0
  15. gov_uk_dashboards/constants.py +5 -0
  16. gov_uk_dashboards/lib/datetime_functions/__init__.py +0 -0
  17. gov_uk_dashboards/lib/datetime_functions/datetime_functions.py +345 -0
  18. {gov_uk_dashboards-13.5.2.dist-info → gov_uk_dashboards-15.0.0.dist-info}/METADATA +1 -1
  19. {gov_uk_dashboards-13.5.2.dist-info → gov_uk_dashboards-15.0.0.dist-info}/RECORD +53 -47
  20. {gov_uk_dashboards-13.5.2.dist-info → gov_uk_dashboards-15.0.0.dist-info}/WHEEL +1 -1
  21. /gov_uk_dashboards/components/{plotly → dash}/apply_and_reset_filters_buttons.py +0 -0
  22. /gov_uk_dashboards/components/{plotly → dash}/banners.py +0 -0
  23. /gov_uk_dashboards/components/{plotly → dash}/card.py +0 -0
  24. /gov_uk_dashboards/components/{plotly → dash}/card_full_width.py +0 -0
  25. /gov_uk_dashboards/components/{plotly → dash}/collapsible_panel.py +0 -0
  26. /gov_uk_dashboards/components/{plotly → dash}/comparison_la_filter_button.py +0 -0
  27. /gov_uk_dashboards/components/{plotly → dash}/context_banner.py +0 -0
  28. /gov_uk_dashboards/components/{plotly → dash}/dashboard_container.py +0 -0
  29. /gov_uk_dashboards/components/{plotly → dash}/details.py +0 -0
  30. /gov_uk_dashboards/components/{plotly → dash}/download_button.py +0 -0
  31. /gov_uk_dashboards/components/{plotly → dash}/footer.py +0 -0
  32. /gov_uk_dashboards/components/{plotly → dash}/graph.py +0 -0
  33. /gov_uk_dashboards/components/{plotly → dash}/header.py +0 -0
  34. /gov_uk_dashboards/components/{plotly → dash}/heading.py +0 -0
  35. /gov_uk_dashboards/components/{plotly → dash}/html_list.py +0 -0
  36. /gov_uk_dashboards/components/{plotly → dash}/key_value_pair.py +0 -0
  37. /gov_uk_dashboards/components/{plotly → dash}/main_content.py +0 -0
  38. /gov_uk_dashboards/components/{plotly → dash}/navbar.py +0 -0
  39. /gov_uk_dashboards/components/{plotly → dash}/no_data_message.py +0 -0
  40. /gov_uk_dashboards/components/{plotly → dash}/notification_banner.py +0 -0
  41. /gov_uk_dashboards/components/{plotly → dash}/paragraph.py +0 -0
  42. /gov_uk_dashboards/components/{plotly → dash}/phase_banner.py +0 -0
  43. /gov_uk_dashboards/components/{plotly → dash}/row_component.py +0 -0
  44. /gov_uk_dashboards/components/{plotly → dash}/side_navbar.py +0 -0
  45. /gov_uk_dashboards/components/{plotly → dash}/tooltip.py +0 -0
  46. /gov_uk_dashboards/components/{plotly → dash}/tooltip_title.py +0 -0
  47. /gov_uk_dashboards/components/{plotly → dash}/visualisation_commentary.py +0 -0
  48. /gov_uk_dashboards/components/{plotly → dash}/visualisation_title.py +0 -0
  49. /gov_uk_dashboards/components/{plotly → dash}/warning_text.py +0 -0
  50. /gov_uk_dashboards/components/{plotly → helpers}/generate_dash_graph_from_figure.py +0 -0
  51. /gov_uk_dashboards/{lib → components/helpers}/update_layout_bgcolor_margin.py +0 -0
  52. {gov_uk_dashboards-13.5.2.dist-info → gov_uk_dashboards-15.0.0.dist-info}/licenses/LICENSE +0 -0
  53. {gov_uk_dashboards-13.5.2.dist-info → gov_uk_dashboards-15.0.0.dist-info}/top_level.txt +0 -0
@@ -4,4 +4,4 @@ using different systems.
4
4
  Contains:
5
5
  - plotly: Module containing Plotly/Dash components
6
6
  """
7
- from . import plotly
7
+ from . import dash
@@ -0,0 +1,92 @@
1
+ """Module containing Dash components for building GOV.UK Design System dashboards.
2
+
3
+ See: https://design-system.service.gov.uk/components/
4
+
5
+ Contains:
6
+ - message_banner: Return a changelog banner to be used to communicate to the
7
+ user when the dashboard was last updated.
8
+ - captioned_figure: Return figure with attached captions that can be read
9
+ by a screen reader.
10
+ - card: Return a rectangle with a grey background. Mostly used to wrap
11
+ individual visualisations.
12
+ - card_full_width: Return a card with a grey background that fits the full
13
+ width of its parent container using CSS flexbox.
14
+ - empty_card: Return an empty card that is hidden to help keep alignment with
15
+ rows and columns.
16
+ - collapsible_panel: Return a component that allows the user to open and close
17
+ a collapsible panel containing child components.
18
+ - dashboard_container: Return a HTML wrapper for a whole dashboard.
19
+ - details: Return HTML component for showing a summary expandable with more
20
+ information beneath.
21
+ - filter_panel: Return a card with a title that allows the user to select and
22
+ filter metrics on the dashboard.
23
+ - hidden_filter: Return an empty, invisible HTML element that stands in for a
24
+ filter component.
25
+ - footer: Return a component for a Gov.UK standard footer.
26
+ - graph: Takes a Plotly Figure and returns a responsive Dash graph with useful
27
+ defaults.
28
+ - heading1: Return a H1 Dash component with gov.uk styling
29
+ - heading2: Return a H1 Dash component with gov.uk styling
30
+ - heading3: Return a H1 Dash component with gov.uk styling
31
+ - HeadingSizes: Enum of sizes that can be used to manually adjust
32
+ text size for heading function returns.
33
+ - html_list: Return either a <ul> or <ol> component, with the children set as
34
+ a list of <li> components matching the list_items provided.
35
+ - key_value_pair: Return an element that displays a value (such as a metric)
36
+ labelled by a key (such as the name of the metric).
37
+ - main_content: Return wrapper for the main content of the dashboard,
38
+ containing visualisations.
39
+ - navbar: Return a navigation bar for switching between dashboards.
40
+ - navbar_link: Return a link for use with the navbar.
41
+ - navbar_link_active: Return a link that appears highlighted, suggesting to
42
+ the user that they are already viewing the linked dashboard.
43
+ - side_navbar: Return a navigation bar for switching between dashboards.
44
+ - side_navbar_link: Return a link for use with the side_navbar.
45
+ - side_navbar_link_active: Return a link that appears highlighted,
46
+ suggesting to the user that they are already viewing the linked
47
+ dashboard.
48
+ - no_data_message: Return a list of strings with a message for when
49
+ selection does not provide data.
50
+ - paragraph: Return a formatted <p> html component with the children provided.
51
+ - ParagraphSizes: Enum for use with paragraph to specify the text size.
52
+ - phase_banner_with_feedback: Return a phase banner with a feedback link,
53
+ which can be specified.
54
+ - row_component: Returns a horizontal row used to contain cards.
55
+ - table_from_dataframe: Return a html table created from a pandas DataFrame.
56
+ - tooltip_title: Return a tooltip component for explaining details.
57
+ - format_visualisation_commentary: Return paragraph styling commentary.
58
+ - format_visualisation_title: Return a default formatted title for a
59
+ visualisation.
60
+ - apply_and_reset_filters_buttons: Add apply filters and reset filters buttons, whcih are aligned to
61
+ the right
62
+ - add_filter_button: Return a 'Compare to additional authority' button which is aligned to the right
63
+ """
64
+
65
+ from .banners import message_banner
66
+ from ..plotly.captioned_figure import captioned_figure
67
+ from .card import card, empty_card
68
+ from .card_full_width import card_full_width
69
+ from .apply_and_reset_filters_buttons import apply_and_reset_filters_buttons
70
+ from .download_button import download_button
71
+ from .download_button import download_button_with_icon
72
+ from .collapsible_panel import collapsible_panel
73
+ from .dashboard_container import dashboard_container
74
+ from .details import details
75
+ from .filter_panel import filter_panel, hidden_filter
76
+ from .footer import footer
77
+ from .graph import graph
78
+ from .heading import heading1, heading2, heading3, HeadingSizes
79
+ from .html_list import html_list
80
+ from .key_value_pair import key_value_pair
81
+ from .main_content import main_content
82
+ from .navbar import navbar, navbar_link, navbar_link_active
83
+ from .no_data_message import no_data_message
84
+ from .paragraph import paragraph, ParagraphSizes
85
+ from .phase_banner import phase_banner_with_feedback
86
+ from .row_component import row_component
87
+ from .side_navbar import side_navbar
88
+ from .table import table_from_dataframe
89
+ from .tooltip_title import tooltip_title
90
+ from .visualisation_commentary import format_visualisation_commentary
91
+ from .visualisation_title import format_visualisation_title
92
+ from .comparison_la_filter_button import add_filter_button
@@ -1,7 +1,7 @@
1
1
  """create_download_chart_button"""
2
2
 
3
3
  from dash import html
4
- from gov_uk_dashboards.components.plotly import download_button_with_icon
4
+ from gov_uk_dashboards.components.dash import download_button_with_icon
5
5
 
6
6
 
7
7
  def create_download_chart_button(button_id_name: str) -> html.Div:
@@ -1,7 +1,7 @@
1
1
  """create_download_data_button"""
2
2
 
3
3
  from dash import html
4
- from gov_uk_dashboards.components.plotly import download_button_with_icon
4
+ from gov_uk_dashboards.components.dash import download_button_with_icon
5
5
 
6
6
 
7
7
  def create_download_data_button(button_id_name: str) -> html.Div:
@@ -2,7 +2,7 @@
2
2
  from typing import Optional
3
3
  from dash import html
4
4
 
5
- from gov_uk_dashboards.components.plotly.heading import heading2
5
+ from gov_uk_dashboards.components.dash.heading import heading2
6
6
  from .collapsible_panel import collapsible_panel
7
7
  from .row_component import row_component
8
8
 
@@ -2,8 +2,8 @@
2
2
  from typing import Optional
3
3
  from pandas import DataFrame
4
4
  from dash import html, dcc
5
- from gov_uk_dashboards.components.plotly.card import card
6
- from gov_uk_dashboards.components.plotly.paragraph import paragraph
5
+ from gov_uk_dashboards.components.dash.card import card
6
+ from gov_uk_dashboards.components.dash.paragraph import paragraph
7
7
 
8
8
  # from gov_uk_dashboards.components.plotly.row_component import row_component
9
9
 
File without changes
@@ -2,14 +2,14 @@
2
2
 
3
3
  from dash import html
4
4
  from dash.development.base_component import Component
5
- from gov_uk_dashboards.components.create_download_chart_button import (
5
+
6
+ from gov_uk_dashboards.components.dash.create_download_chart_button import (
6
7
  create_download_chart_button,
7
8
  )
8
- from gov_uk_dashboards.components.create_download_data_button import (
9
+ from gov_uk_dashboards.components.dash.create_download_data_button import (
9
10
  create_download_data_button,
10
11
  )
11
-
12
- from gov_uk_dashboards.components.plotly.heading import HeadingSizes
12
+ from gov_uk_dashboards.components.dash.heading import HeadingSizes
13
13
 
14
14
 
15
15
  def display_chart_or_table_with_header(
@@ -27,3 +27,20 @@ def get_legend_configuration(itemclick=True, itemdoubleclick=True):
27
27
  "itemclick": "toggle" if itemclick else False,
28
28
  "itemdoubleclick": "toggle" if itemdoubleclick else False,
29
29
  }
30
+
31
+
32
+ def get_rgba_from_hex_colour_and_alpha(hex_code: str, alpha: float = 1.0) -> str:
33
+ """Get the rgba string corresponding to a hex-code colour and its alpha (opacity)
34
+
35
+ Args:
36
+ hex_code (str): hex code for converting (with #), e.g. "#00FF00"
37
+ alpha (float, optional): Desired transparency from 0 to 1. Defaults to 1.0.
38
+
39
+ Returns:
40
+ str: rgba string
41
+ """
42
+ if hex_code[0] != "#" or len(hex_code) != 7:
43
+ raise ValueError
44
+ rgb_colour = tuple(int(hex_code[i : i + 2], 16) for i in (1, 3, 5))
45
+
46
+ return f"rgba{rgb_colour + (alpha,)}"
@@ -1,92 +0,0 @@
1
- """Module containing Plotly/Dash components for building GOV.UK Design System dashboards.
2
-
3
- See: https://design-system.service.gov.uk/components/
4
-
5
- Contains:
6
- - message_banner: Return a changelog banner to be used to communicate to the
7
- user when the dashboard was last updated.
8
- - captioned_figure: Return figure with attached captions that can be read
9
- by a screen reader.
10
- - card: Return a rectangle with a grey background. Mostly used to wrap
11
- individual visualisations.
12
- - card_full_width: Return a card with a grey background that fits the full
13
- width of its parent container using CSS flexbox.
14
- - empty_card: Return an empty card that is hidden to help keep alignment with
15
- rows and columns.
16
- - collapsible_panel: Return a component that allows the user to open and close
17
- a collapsible panel containing child components.
18
- - dashboard_container: Return a HTML wrapper for a whole dashboard.
19
- - details: Return HTML component for showing a summary expandable with more
20
- information beneath.
21
- - filter_panel: Return a card with a title that allows the user to select and
22
- filter metrics on the dashboard.
23
- - hidden_filter: Return an empty, invisible HTML element that stands in for a
24
- filter component.
25
- - footer: Return a component for a Gov.UK standard footer.
26
- - graph: Takes a Plotly Figure and returns a responsive Dash graph with useful
27
- defaults.
28
- - heading1: Return a H1 Dash component with gov.uk styling
29
- - heading2: Return a H1 Dash component with gov.uk styling
30
- - heading3: Return a H1 Dash component with gov.uk styling
31
- - HeadingSizes: Enum of sizes that can be used to manually adjust
32
- text size for heading function returns.
33
- - html_list: Return either a <ul> or <ol> component, with the children set as
34
- a list of <li> components matching the list_items provided.
35
- - key_value_pair: Return an element that displays a value (such as a metric)
36
- labelled by a key (such as the name of the metric).
37
- - main_content: Return wrapper for the main content of the dashboard,
38
- containing visualisations.
39
- - navbar: Return a navigation bar for switching between dashboards.
40
- - navbar_link: Return a link for use with the navbar.
41
- - navbar_link_active: Return a link that appears highlighted, suggesting to
42
- the user that they are already viewing the linked dashboard.
43
- - side_navbar: Return a navigation bar for switching between dashboards.
44
- - side_navbar_link: Return a link for use with the side_navbar.
45
- - side_navbar_link_active: Return a link that appears highlighted,
46
- suggesting to the user that they are already viewing the linked
47
- dashboard.
48
- - no_data_message: Return a list of strings with a message for when
49
- selection does not provide data.
50
- - paragraph: Return a formatted <p> html component with the children provided.
51
- - ParagraphSizes: Enum for use with paragraph to specify the text size.
52
- - phase_banner_with_feedback: Return a phase banner with a feedback link,
53
- which can be specified.
54
- - row_component: Returns a horizontal row used to contain cards.
55
- - table_from_dataframe: Return a html table created from a pandas DataFrame.
56
- - tooltip_title: Return a tooltip component for explaining details.
57
- - format_visualisation_commentary: Return paragraph styling commentary.
58
- - format_visualisation_title: Return a default formatted title for a
59
- visualisation.
60
- - apply_and_reset_filters_buttons: Add apply filters and reset filters buttons, whcih are aligned to
61
- the right
62
- - add_filter_button: Return a 'Compare to additional authority' button which is aligned to the right
63
- """
64
-
65
- from .banners import message_banner
66
- from .captioned_figure import captioned_figure
67
- from .card import card, empty_card
68
- from .card_full_width import card_full_width
69
- from .apply_and_reset_filters_buttons import apply_and_reset_filters_buttons
70
- from .download_button import download_button
71
- from .download_button import download_button_with_icon
72
- from .collapsible_panel import collapsible_panel
73
- from .dashboard_container import dashboard_container
74
- from .details import details
75
- from .filter_panel import filter_panel, hidden_filter
76
- from .footer import footer
77
- from .graph import graph
78
- from .heading import heading1, heading2, heading3, HeadingSizes
79
- from .html_list import html_list
80
- from .key_value_pair import key_value_pair
81
- from .main_content import main_content
82
- from .navbar import navbar, navbar_link, navbar_link_active
83
- from .no_data_message import no_data_message
84
- from .paragraph import paragraph, ParagraphSizes
85
- from .phase_banner import phase_banner_with_feedback
86
- from .row_component import row_component
87
- from .side_navbar import side_navbar
88
- from .table import table_from_dataframe
89
- from .tooltip_title import tooltip_title
90
- from .visualisation_commentary import format_visualisation_commentary
91
- from .visualisation_title import format_visualisation_title
92
- from .comparison_la_filter_button import add_filter_button
@@ -7,7 +7,7 @@ from dash import dcc
7
7
  from gov_uk_dashboards.constants import DEFAULT_COLOURSCALE
8
8
 
9
9
  from gov_uk_dashboards import colours
10
- from gov_uk_dashboards.components.display_chart_or_table_with_header import (
10
+ from gov_uk_dashboards.components.helpers.display_chart_or_table_with_header import (
11
11
  display_chart_or_table_with_header,
12
12
  )
13
13
 
@@ -0,0 +1,34 @@
1
+ """Classes to be used for defined enums and type structures"""
2
+
3
+ from enum import Enum
4
+ from typing import TypedDict
5
+
6
+
7
+ class XAxisFormat(Enum):
8
+ """Enum for date format on x axis"""
9
+
10
+ YEAR = "year"
11
+ MONTH_YEAR = "month_year"
12
+ FINANCIAL_QUARTER = "financial_quarter"
13
+
14
+
15
+ class TitleDataStructure(TypedDict):
16
+ """A TypedDict representing the structure of title_data"""
17
+
18
+ MAIN_TITLE: str
19
+ SUBTITLE: str
20
+
21
+
22
+ class HoverDataStructure(TypedDict):
23
+ """A TypedDict representing the structure of hover_data"""
24
+
25
+ CUSTOM_DATA: list[str]
26
+ HOVER_TEXT_HEADERS: list[str]
27
+
28
+
29
+ class HoverDataByTrace(TypedDict):
30
+ """A TypedDict representing hover_data organized by tracename"""
31
+
32
+ tracename: dict[
33
+ str, HoverDataStructure
34
+ ] # Each tracename maps to a HoverDataStructure
@@ -1,8 +1,7 @@
1
1
  """stacked_barchart function"""
2
2
 
3
- from enum import Enum
4
3
  import math
5
- from typing import Optional, TypedDict
4
+ from typing import Optional
6
5
  from dash import html
7
6
  import polars as pl
8
7
 
@@ -20,50 +19,27 @@ from gov_uk_dashboards.constants import (
20
19
  VALUE,
21
20
  )
22
21
  from gov_uk_dashboards.colours import AFAccessibleColours
23
- from gov_uk_dashboards.components.display_chart_or_table_with_header import (
22
+ from gov_uk_dashboards.components.helpers.display_chart_or_table_with_header import (
24
23
  display_chart_or_table_with_header,
25
24
  )
26
- from gov_uk_dashboards.components.plotly.generate_dash_graph_from_figure import (
25
+ from gov_uk_dashboards.components.helpers.generate_dash_graph_from_figure import (
27
26
  generate_dash_graph_from_figure,
28
27
  )
29
- from gov_uk_dashboards.lib.plotting_helper_functions import get_legend_configuration
28
+ from gov_uk_dashboards.components.helpers.plotting_helper_functions import (
29
+ get_legend_configuration,
30
+ )
31
+ from gov_uk_dashboards.components.plotly.enums import (
32
+ HoverDataByTrace,
33
+ TitleDataStructure,
34
+ XAxisFormat,
35
+ )
30
36
  from gov_uk_dashboards.formatting.human_readable import format_as_human_readable
31
37
 
32
- from gov_uk_dashboards.lib.update_layout_bgcolor_margin import (
38
+ from gov_uk_dashboards.components.helpers.update_layout_bgcolor_margin import (
33
39
  update_layout_bgcolor_margin,
34
40
  )
35
41
 
36
42
 
37
- class XAxisFormat(Enum):
38
- """Enum for date format on x axis"""
39
-
40
- YEAR = "year"
41
- MONTH_YEAR = "month_year"
42
- FINANCIAL_QUARTER = "financial_quarter"
43
-
44
-
45
- class TitleDataStructure(TypedDict):
46
- """A TypedDict representing the structure of title_data"""
47
-
48
- MAIN_TITLE: str
49
- SUBTITLE: str
50
-
51
-
52
- class HoverDataStructure(TypedDict):
53
- """A TypedDict representing the structure of hover_data"""
54
-
55
- CUSTOM_DATA: list[str]
56
- HOVER_TEXT_HEADERS: list[str]
57
-
58
-
59
- class HoverDataByTrace(TypedDict):
60
- """A TypedDict representing hover_data organized by tracename"""
61
-
62
- tracename: dict[
63
- str, HoverDataStructure
64
- ] # Each tracename maps to a HoverDataStructure
65
-
66
-
67
43
  class StackedBarChart:
68
44
  """Class for use in generating stacked bar charts."""
69
45