afcharts 1.0.0a0__tar.gz

afcharts-1.0.0a0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Crown Copyright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

afcharts-1.0.0a0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: afcharts
+Version: 1.0.0a0
+Summary: A python package to produce charts following UK Government Analysis Function guidance
+Author: Crown Copyright
+Maintainer-email: Nick Henden <Nick.Henden@ukhsa.gov.uk>, Tom Farley <tom.farley@ukhsa.gov.uk>, Stelios Georgiou <Stelios.Georgiou@ukhsa.gov.uk>, Frederico Rodrigues <fred.rodrigues@defra.gov.uk>, Peter Brohan <peter.brohan@communities.gov.uk>, Fahim Hossain <fahim.hossain@ukhsa.gov.uk>
+Project-URL: Homepage, https://github.com/best-practice-and-impact/afcharts-py
+Project-URL: Documentation, https://best-practice-and-impact.github.io/afcharts-py/
+Project-URL: Source, https://github.com/best-practice-and-impact/afcharts-py
+Project-URL: Issue Tracker, https://github.com/best-practice-and-impact/afcharts-py/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: plotly>=6.1.2
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: PyYAML>=5.0
+Dynamic: license-file
+
+
+# afcharts-py <img src="docs/images/logo.svg" alt="afcharts logo" align="right" height="150"/>
+
+## Overview
+
+The afcharts python package helps make accessible Matplotlib and Plotly charts following [Government Analysis Function Data Visualisation guidance](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-charts/):
+
+- **Automatic chart formatting** with pre-built style sheets for Matplotlib and Plotly
+- **Chart colours** from the Analysis Function [accessible colour palettes](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-4)
+- **Example code** for common chart types in the [cookbook](https://best-practice-and-impact.github.io/afcharts-py/)
+
+Looking for the R version? Check out the [afcharts R package](https://best-practice-and-impact.github.io/afcharts/).
+
+<img src="docs/images/example_charts/bar_chart-matplotlib_afcharts.png" width="28.1%" alt="A grouped bar chart in afcharts style showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/scatterplot-matplotlib_afcharts.png" width="30%" alt="A scatterplot in afcharts style showing life expectancy against GDP per capita for 142 countries in 2007."/> <img src="docs/images/example_charts/line_chart-matplotlib_afcharts.png" width="37.5%" alt="A line chart in afcharts style showing life expectancy in China and the UK from 1952 to 2007"/>
+
+## Installation
+
+afcharts is available at the Python Package Index (PyPI):
+```bash
+pip install afcharts
+```
+or see the [alternative installation](https://best-practice-and-impact.github.io/afcharts-py/getting-started.html) instructions.
+
+## Usage
+
+Format any Matplotlib or Plotly chart in the Analysis Function style using the built-in style sheets.
+
+See the [Getting Started](https://best-practice-and-impact.github.io/afcharts-py/getting-started.html) guide for more options and the [cookbook](https://best-practice-and-impact.github.io/afcharts-py/) for extensive examples.
+
+### Matplotlib
+
+```python
+import matplotlib.pyplot as plt
+
+# Apply the afcharts style to all Matplotlib plots
+plt.style.use('afcharts.afcharts')
+```
+
+Example: A [Matplotlib bar chart](https://best-practice-and-impact.github.io/afcharts-py/01-matplotlib-usage.html#grouped-bar-chart) with afcharts (left) and without (right)
+
+<img src="docs/images/example_charts/bar_chart-matplotlib_afcharts.png" width="35%" alt="Grouped bar chart (afcharts style) showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/bar_chart-matplotlib_default.png" width="34.7%" alt="Grouped bar chart (default Matplotlib) showing life expectancy in 1967 and 2007 for four countries. Bars: blue for 1967, orange for 2007."/>
+
+### Plotly
+
+```python
+from afcharts.pio_template import pio
+
+# Apply the afcharts style to all Plotly plots
+pio.templates.default = "afcharts"
+```
+
+Example: A [Plotly bar chart](https://best-practice-and-impact.github.io/afcharts-py/03-plotly-usage.html#grouped-bar-chart) with afcharts (left) and without (right)
+
+<img src="docs/images/example_charts/bar_chart-plotly_afcharts.png" width="35%" alt="Grouped bar chart (afcharts style) showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/bar_chart-plotly_default.png" width="35%" alt="Grouped bar chart (default Plotly) showing life expectancy in 1967 and 2007 for four countries. Bars: blue for 1967, red for 2007."/>
+
+### Colours
+
+Easily return a list of colours from any of the Analysis Function [accessible colour palettes](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-4) with the `get_af_colours()` function:
+
+```python
+from afcharts.af_colours import get_af_colours
+
+# Get the duo colour palette hex codes
+duo = get_af_colours("duo")
+```
+
+## Getting help
+If you encounter a bug, please file a minimal reproducible example on [Github Issues](https://github.com/best-practice-and-impact/afcharts-py/issues). For questions and other discussion, please start a [discussion](https://github.com/best-practice-and-impact/afcharts-py/discussions).
+
+## Contributing
+Interested in contributing? Check out the [contributing guidelines](CONTRIBUTING.md). 
+
+## Acknowledgments
+The afcharts python package is based on the
+[afcharts](https://github.com/best-practice-and-impact/afcharts.git) R package and the [py-af-colours](https://github.com/best-practice-and-impact/py-af-colours) package.
+
+## License
+Unless stated otherwise, the codebase is released under [the MIT License](LICENSE.md). This covers both the codebase and any sample code in the documentation.
+
+The documentation is [© Crown copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government 3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) licence.

afcharts-1.0.0a0/README.md

@@ -0,0 +1,80 @@
+
+# afcharts-py <img src="docs/images/logo.svg" alt="afcharts logo" align="right" height="150"/>
+
+## Overview
+
+The afcharts python package helps make accessible Matplotlib and Plotly charts following [Government Analysis Function Data Visualisation guidance](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-charts/):
+
+- **Automatic chart formatting** with pre-built style sheets for Matplotlib and Plotly
+- **Chart colours** from the Analysis Function [accessible colour palettes](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-4)
+- **Example code** for common chart types in the [cookbook](https://best-practice-and-impact.github.io/afcharts-py/)
+
+Looking for the R version? Check out the [afcharts R package](https://best-practice-and-impact.github.io/afcharts/).
+
+<img src="docs/images/example_charts/bar_chart-matplotlib_afcharts.png" width="28.1%" alt="A grouped bar chart in afcharts style showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/scatterplot-matplotlib_afcharts.png" width="30%" alt="A scatterplot in afcharts style showing life expectancy against GDP per capita for 142 countries in 2007."/> <img src="docs/images/example_charts/line_chart-matplotlib_afcharts.png" width="37.5%" alt="A line chart in afcharts style showing life expectancy in China and the UK from 1952 to 2007"/>
+
+## Installation
+
+afcharts is available at the Python Package Index (PyPI):
+```bash
+pip install afcharts
+```
+or see the [alternative installation](https://best-practice-and-impact.github.io/afcharts-py/getting-started.html) instructions.
+
+## Usage
+
+Format any Matplotlib or Plotly chart in the Analysis Function style using the built-in style sheets.
+
+See the [Getting Started](https://best-practice-and-impact.github.io/afcharts-py/getting-started.html) guide for more options and the [cookbook](https://best-practice-and-impact.github.io/afcharts-py/) for extensive examples.
+
+### Matplotlib
+
+```python
+import matplotlib.pyplot as plt
+
+# Apply the afcharts style to all Matplotlib plots
+plt.style.use('afcharts.afcharts')
+```
+
+Example: A [Matplotlib bar chart](https://best-practice-and-impact.github.io/afcharts-py/01-matplotlib-usage.html#grouped-bar-chart) with afcharts (left) and without (right)
+
+<img src="docs/images/example_charts/bar_chart-matplotlib_afcharts.png" width="35%" alt="Grouped bar chart (afcharts style) showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/bar_chart-matplotlib_default.png" width="34.7%" alt="Grouped bar chart (default Matplotlib) showing life expectancy in 1967 and 2007 for four countries. Bars: blue for 1967, orange for 2007."/>
+
+### Plotly
+
+```python
+from afcharts.pio_template import pio
+
+# Apply the afcharts style to all Plotly plots
+pio.templates.default = "afcharts"
+```
+
+Example: A [Plotly bar chart](https://best-practice-and-impact.github.io/afcharts-py/03-plotly-usage.html#grouped-bar-chart) with afcharts (left) and without (right)
+
+<img src="docs/images/example_charts/bar_chart-plotly_afcharts.png" width="35%" alt="Grouped bar chart (afcharts style) showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/bar_chart-plotly_default.png" width="35%" alt="Grouped bar chart (default Plotly) showing life expectancy in 1967 and 2007 for four countries. Bars: blue for 1967, red for 2007."/>
+
+### Colours
+
+Easily return a list of colours from any of the Analysis Function [accessible colour palettes](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-4) with the `get_af_colours()` function:
+
+```python
+from afcharts.af_colours import get_af_colours
+
+# Get the duo colour palette hex codes
+duo = get_af_colours("duo")
+```
+
+## Getting help
+If you encounter a bug, please file a minimal reproducible example on [Github Issues](https://github.com/best-practice-and-impact/afcharts-py/issues). For questions and other discussion, please start a [discussion](https://github.com/best-practice-and-impact/afcharts-py/discussions).
+
+## Contributing
+Interested in contributing? Check out the [contributing guidelines](CONTRIBUTING.md). 
+
+## Acknowledgments
+The afcharts python package is based on the
+[afcharts](https://github.com/best-practice-and-impact/afcharts.git) R package and the [py-af-colours](https://github.com/best-practice-and-impact/py-af-colours) package.
+
+## License
+Unless stated otherwise, the codebase is released under [the MIT License](LICENSE.md). This covers both the codebase and any sample code in the documentation.
+
+The documentation is [© Crown copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government 3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) licence.

afcharts-1.0.0a0/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "afcharts"
+version = "1.0.0-alpha"
+description = "A python package to produce charts following UK Government Analysis Function guidance"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Crown Copyright" }]
+maintainers = [
+    { name = "Nick Henden", email = "Nick.Henden@ukhsa.gov.uk" },
+    { name = "Tom Farley", email = "tom.farley@ukhsa.gov.uk" },
+    { name = "Stelios Georgiou", email = "Stelios.Georgiou@ukhsa.gov.uk" },
+    { name = "Frederico Rodrigues", email = "fred.rodrigues@defra.gov.uk" },
+    { name = "Peter Brohan", email = "peter.brohan@communities.gov.uk"},
+    { name = "Fahim Hossain", email = "fahim.hossain@ukhsa.gov.uk"}
+    # Other contributors, please add your details here
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+]
+requires-python = ">=3.10"
+
+dependencies = [ # install package dependencies with $ uv sync
+    "matplotlib>=3.10.3",
+    "plotly>=6.1.2",
+    "typeguard>=4.4.4",
+    'PyYAML >= 5.0',
+]
+
+[dependency-groups]
+dev = [ # package developer dependencies are installed by default with $ uv sync
+    "ipython>=8.26.0",   # Installing ipython will enable colourised console output/tracebacks
+    "mypy>=1.15.0",      # Mypy static type checker/linter
+    "types-PyYAML",      # type stub package used by mypy to check code that uses PyYAML
+    "pre-commit>=3.8.0", # Used to run pre-commit hook linting and formatting checks
+    "ruff>=0.6.2",       # Python linting/formatting tool combines black, flake8 etc. Run `ruff check --fix`/`ruff format`
+    "pandas>=2.2.2",     # Used to manipulate tabular data
+    "afcharts",          # Install current package in developer mode as workspace package
+    "ipykernel",         # For rendering Quarto
+    "nbclient",          # For rendering Quarto
+]
+test = [ # package testing dependencies are installed by default with $ uv sync
+    "pandas>=2.2.2",     # Used to manipulate tabular data
+    "pytest>=8.2.2",       # Unit/regression testing etc.
+    "pytest-cov>=5.0.0",   # Test code coverage
+    "pytest-mock",         # Mock wrapper for unit tests
+    "pytest-sugar>=1.0.0", # Prettier pytest terminal output
+]
+
+[project.urls]
+"Homepage" = "https://github.com/best-practice-and-impact/afcharts-py"
+"Documentation" = "https://best-practice-and-impact.github.io/afcharts-py/"
+"Source" = "https://github.com/best-practice-and-impact/afcharts-py"
+"Issue Tracker" = "https://github.com/best-practice-and-impact/afcharts-py/issues"
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "test",
+] # `uv sync` will also install dev and test dependencies by default
+
+[tool.uv.sources]
+afcharts = { workspace = true } # Install as editable package (developer mode like pip install -e .)
+
+[tool.setuptools]
+package-dir = { "" = "src" } # Maps package names to their actual file paths.
+
+[tool.setuptools.packages.find]
+where = ["src"]                                # Packages are located in src/ top level directory
+exclude = ["docs*", "Documentation*", "build"]
+
+[tool.setuptools.package-data]
+afcharts = ["*.mplstyle", "config/af_colours.yaml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+lint.select = [
+    "E",   # pycodestyle
+    "W",   # pycodestyle
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C90", # mccabe cyclomatic complexity
+    "G",   # flake8-logging-format
+]
+exclude = ["migrations/versions/"]
+lint.ignore = []
+
+[tool.ruff.lint.pydocstyle]
+convention = "google" # Accepts one of {google,numpy,pep257}
+
+[tool.mypy] # Config for mypy static type checking
+python_version = "3.13"
+check_untyped_defs = true
+ignore_missing_imports = true
+warn_unused_ignores = true

afcharts-1.0.0a0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

afcharts-1.0.0a0/src/afcharts/__init__.py

@@ -0,0 +1 @@
+

afcharts-1.0.0a0/src/afcharts/af_colours.py

@@ -0,0 +1,259 @@
+# Government Analysis Function (AF) colours and palettes
+# Source: https://analysisfunction.civilservice.gov.uk/policy-store/
+#   data-visualisation-colours-in-charts/
+# Py-af-colours source: https://github.com/best-practice-and-impact/py-af-colours
+
+from pathlib import Path
+
+import yaml
+
+
+def get_af_colours(palette: str, colour_format="hex", number_of_colours=6, config_path=None):
+    """
+    get_af_colours() is the top level function in af_colours. This returns
+    the chosen Analysis Function colour palette in hex or rgb format.
+    For the categorical palette, this can be a chosen number of colours
+    up to 6.
+
+    Parameters
+    ----------
+    palette : string
+        Type of palette required, with accepted values of "duo",
+        "focus", "categorical", and "sequential".
+
+    colour_format : string, optional
+        Colour format required, with accepted values of "hex" or "rgb".
+
+    number_of_colours : int, optional
+        Number of colours required (categorical palette only). Takes
+        values between 2 and 6. Returns 2 colours by default. If a
+        palette other than categorical is chosen, any value passed
+        is ignored.
+
+    config_path : NoneType, optional
+        Takes the default value None, inside the function this is
+        mapped to the relative path independent of operating system.
+        Should not require changing.
+
+    Raises
+    ------
+    ValueError
+        If palette is not "categorical", "duo", "sequential", or "focus".
+        Or if colour_format is not "hex" or "rgb".
+
+    Returns
+    -------
+    list
+        chosen_colours_list
+
+    """
+    if config_path is None:
+        parent_dir = Path(__file__).parent
+        config_path = parent_dir.joinpath("config", "af_colours.yaml")
+
+    with open(config_path) as file:
+        config = yaml.load(file, Loader=yaml.BaseLoader)
+
+    categorical_hex_list = config["categorical_hex_list"]
+    duo_hex_list = config["duo_hex_list"]
+    sequential_hex_list = config["sequential_hex_list"]
+    focus_hex_list = config["focus_hex_list"]
+
+    if palette not in ["categorical", "duo", "sequential", "focus"]:
+        raise ValueError("palette must be one of 'categorical', 'duo', 'sequential' " + f"or 'focus', not {palette}.")
+    if colour_format not in ["hex", "rgb"]:
+        raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
+
+    if number_of_colours < 1:
+        raise ValueError("number_of_colours must be greater than 0.")
+
+    elif palette == "sequential":
+        chosen_colours_list = sequential_colours(sequential_hex_list, colour_format)
+
+    elif palette == "focus":
+        chosen_colours_list = focus_colours(focus_hex_list, colour_format)
+
+    elif palette == "duo":
+        chosen_colours_list = duo_colours(duo_hex_list, colour_format)
+
+    elif palette == "categorical":
+        chosen_colours_list = categorical_colours(categorical_hex_list, duo_hex_list, colour_format, number_of_colours)
+
+    return chosen_colours_list
+
+
+def categorical_colours(categorical_hex_list, duo_hex_list, colour_format="hex", number_of_colours=2):
+    """
+    Return the Analysis Function categorical colour palette as a list
+    in hex or rgb format for up to 6 colours. If number_of_colours is
+    2, the function returns the duo palette.
+
+    Parameters
+    ----------
+    categorical_hex_list : list
+        List of categorical colours as a hex list, stored in the config.
+
+    duo_hex_list : list
+        List of duo hex codes, stored in the config. This is needed for the
+        case of number_of_colours = 2.
+
+    colour_format : string
+        Colour format required, with accepted values of "hex" or "rgb".
+
+    number_of_colours : int
+        Number of colours required, with accepted values between 2 and 6
+        inclusive. Returns 2 colours if no value given.
+
+    Raises
+    ------
+    ValueError
+        If number_of_colours is greater than 6.
+
+    Returns
+    -------
+    list
+        categorical_colours_list
+
+    """
+
+    if number_of_colours > 6:
+        raise ValueError("number_of_colours must not be more than 6 for the categorical palette.")
+
+    if number_of_colours == 2:
+        categorical_colours_list = duo_colours(duo_hex_list, colour_format)
+        return categorical_colours_list
+
+    elif colour_format == "hex":
+        full_categorical_colours_list = categorical_hex_list
+
+    elif colour_format == "rgb":
+        full_categorical_colours_list = hex_to_rgb(categorical_hex_list)
+
+    else:
+        raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
+
+    categorical_colours_list = full_categorical_colours_list[0:number_of_colours]
+
+    return categorical_colours_list
+
+
+def duo_colours(duo_hex_list, colour_format="hex"):
+    """
+    Return the Analysis Function duo colour palette as a list of 2
+    colours in hex or rgb format. This function is also called by
+    sequential_colours() if number_of_colours is equal to 2.
+
+    Parameters
+    ----------
+    duo_hex_list : list
+        List of duo colours hex codes, stored in the config. This is needed for the
+        case of number_of_colours = 2.
+
+    colour_format : string
+        Colour format required, with accepted values of "hex" or "rgb".
+
+    Returns
+    -------
+    list
+        duo_colours_list
+
+    """
+
+    if colour_format == "hex":
+        duo_colours_list = duo_hex_list
+    elif colour_format == "rgb":
+        duo_colours_list = hex_to_rgb(duo_hex_list)
+    else:
+        raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
+
+    return duo_colours_list
+
+
+def sequential_colours(sequential_hex_list, colour_format="hex"):
+    """
+    Return the Analysis Function sequential colour palette as a list
+    of 3 colours in hex or rgb format.
+
+    Parameters
+    ----------
+    sequential_hex_list : list
+        List of sequential colours hex codes, stored in the config.
+
+    colour_format : string
+        Colour format required, with accepted values of "hex" or "rgb".
+
+    Returns
+    -------
+    list
+        sequential_colours_list
+
+    """
+
+    if colour_format == "hex":
+        sequential_colours_list = sequential_hex_list
+    elif colour_format == "rgb":
+        sequential_colours_list = hex_to_rgb(sequential_hex_list)
+    else:
+        raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
+
+    return sequential_colours_list
+
+
+def focus_colours(focus_hex_list, colour_format="hex"):
+    """
+    Return the Analysis Function focus colour palette as a list of 2
+    colours in hex or rgb format.
+
+    Parameters
+    ----------
+    focus_hex_list : list
+        List of focus colours hex codes, stored in the config.
+
+    colour_format : string
+        Colour format required, with accepted values of "hex" or "rgb".
+
+    Returns
+    -------
+    list
+        focus_colours_list
+
+    """
+
+    if colour_format == "hex":
+        focus_colours_list = focus_hex_list
+    elif colour_format == "rgb":
+        focus_colours_list = hex_to_rgb(focus_hex_list)
+    else:
+        raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
+
+    return focus_colours_list
+
+
+def hex_to_rgb(hex_colours):
+    """
+    Convert a list of hex codes to a list of rgb colours.
+
+    Parameters
+    ----------
+    hex_colours : list
+        The hex colours to be converted as a list of strings, with or
+        without # at the beginning.
+
+    Raises
+    ------
+    TypeError
+        If hex_colours is not a list.
+
+    Returns
+    -------
+    list
+        converted_list
+
+    """
+    if type(hex_colours) is not list:
+        raise TypeError("hex_colours must be a list.")
+
+    hex_colours_new = [i.lstrip("#") for i in hex_colours]
+
+    converted_list = [(tuple(int(value[i : i + 2], 16) for i in (0, 2, 4))) for value in hex_colours_new]
+    return converted_list

afcharts-1.0.0a0/src/afcharts/afcharts.mplstyle

@@ -0,0 +1,42 @@
+# TEXT
+font.size : 14
+font.family : sans-serif
+font.sans-serif : Arial, Helvetica, DejaVu Sans, Bitstream Vera Sans, Computer Modern Sans Serif, Lucida Grande, Verdana, Geneva, Lucid, Avant Garde, sans-serif
+text.color : black
+axes.titlelocation: left
+
+# AXES
+axes.edgecolor : (0.8,0.8,0.8)
+axes.labelcolor : (0.1,0.1,0.1)
+axes.linewidth : 1
+axes.spines.top : False
+axes.spines.right : False
+axes.spines.bottom : True
+axes.spines.left : False
+axes.axisbelow : True
+
+# GRID
+axes.grid : True
+axes.grid.axis : y
+axes.grid.which : major
+grid.color : '0.8'
+grid.linestyle : -
+grid.linewidth : 0.6
+
+# LINES
+axes.prop_cycle: cycler('color', ["#12436D","#28A197","#801650", "#F46A25","#3D3D3D","#A285D1"])
+lines.linewidth : 2
+
+# TICKS
+xtick.color : (0.8,0.8,0.8)
+xtick.labelcolor : (0.1,0.1,0.1)
+xtick.direction : out
+ytick.color : (0.8,0.8,0.8)
+ytick.labelcolor : (0.1,0.1,0.1)
+ytick.direction : out
+
+# LEGEND
+legend.frameon : False
+
+# FIGURE OUTPUT 
+figure.figsize : 6.4, 4.8

afcharts-1.0.0a0/src/afcharts/config/af_colours.yaml

@@ -0,0 +1,4 @@
+categorical_hex_list: ["#12436D","#28A197","#801650", "#F46A25","#3D3D3D","#A285D1"]
+duo_hex_list: ["#12436D","#F46A25"]
+sequential_hex_list: ["#12436D", "#2073BC", "#6BACE6"]
+focus_hex_list: ["#12436D","#BFBFBF"]

afcharts-1.0.0a0/src/afcharts/pio_template.py

@@ -0,0 +1,142 @@
+import plotly.graph_objects as go
+import plotly.io as pio
+
+from afcharts.af_colours import get_af_colours
+
+# References:
+# https://plotly.com/python/templates/
+# https://plotly.com/python-api-reference/generated/plotly.graph_objects.layout.template.html
+
+# Use built in sans font
+afcharts_font = "Sans-serif"  # consider using a different font?
+
+# R package ggplot uses pt as dimmentions whereas plotly uses px
+# 1 pt ≈ 1.33 px
+# So a 14 pt font ≈ 18.62 px in Plotly
+base_size = 14 * 1.33
+base_line_size = base_size / 24
+base_rect_size = base_size / 24
+
+# The half-line (base_size / 2) sets up the basic vertical
+# rhythm of the theme. Most margins will be set to this value.
+# However, when we work with relative sizes, we may want to multiply
+# `half_line` with the appropriate relative size. This applies in
+# particular for axis tick sizes. And also, for axis ticks and
+# axis titles, `half_size` is too large a distance, and we use `half_size/2`
+# instead.
+half_line = base_size / 2
+
+af_chart_feature_colour = "#D6D6D6"
+
+pio.templates["afcharts"] = go.layout.Template(
+    layout={
+        "autosize": True,  # Automatically adjusts the scale of the plot based on it's content
+        "annotationdefaults": {
+            "font": {"size": base_size},
+            "showarrow": False,
+        },  # Sets default font size for annotation
+        "bargap": 0.15,
+        "bargroupgap": 0.1,
+        "coloraxis": {
+            "colorbar": {  # Bar chart colours
+                "outlinewidth": 0,  # Width of the outline around the color bar
+                "tickcolor": af_chart_feature_colour,  # Bar chart tick colour
+                "ticklen": half_line / 2,  # Bar chart tick length
+                "ticks": "outside",  # Bar chart tick position
+            }
+        },
+        "colorscale": {
+            "sequential": get_af_colours("sequential")[
+                ::-1
+            ]  # reverse to make high = dark  # Sequential colour scale for low to high ranges
+        },
+        "colorway": get_af_colours("categorical"),  # Sequence of colours to be used in plots
+        "font": {
+            "color": "black",  # Text colour
+            "family": afcharts_font,  # Font
+            "size": base_size,
+        },  # Text size
+        "legend_title": None,  # Removes legend title
+        "legend": {
+            "borderwidth": 0,
+            "title": {"text": None},  # Removes legend title
+            "font": {"size": base_size},  # Legend font size
+            "bgcolor": "rgba(0,0,0,0)",  # Makes legend background transparent
+            "orientation": "v",  # Legend orientation
+            "x": 1,  # Positions legend (0,0 is the bottom left)
+            "y": 0.5,
+            "indentation": 0,
+            "itemclick": "toggleothers",  # Change behaviour from hiding trace to showing only this trace
+            "itemwidth": 30,
+            "traceorder": "normal",
+        },
+        "hoverlabel": {
+            "align": "left",  # Align hover label text to the left
+            "font_size": base_size * 0.9,  # Text size of hover
+            "bgcolor": "white",  # Hover box background
+        },
+        "hovermode": "x unified",  # How hovering affects the display
+        # x unified shows info for all the data at that point in the x-axis
+        "margin": {  # Set margins around the plot area in pixels
+            "l": half_line,  # Left margin
+            "r": half_line,  # Right margin
+            "t": half_line,  # Top margin
+            "b": half_line,  # Bottom margin
+            "pad": 0,  # Padding between grid lines and the tick labels
+        },
+        "uniformtext_minsize": 8,  # Minimum font size for text elements in the plot
+        "uniformtext_mode": "hide",  # Controls visibility of text based on size then the
+        # text will be hidden - hide means that if a text element's size falls below the "uniformtext_minsize"
+        "title": {
+            "text": None,
+            "font": {
+                "size": base_size * 1.6,
+            },  # Title font size and colour
+            "x": 0,
+            "xref": "paper",  # Title alignment
+            "pad": {
+                "t": half_line,
+                "l": 0,
+                "r": half_line,
+                "b": half_line,
+            },  # Padding above and below title
+        },
+        "xaxis": {  # Configures the x-axis
+            "automargin": True,  # Automatically adjust margins on axes to fit the content
+            "gridcolor": af_chart_feature_colour,  # Grid lines colours
+            "linecolor": af_chart_feature_colour,  # Axes line colour
+            "linewidth": 1,
+            "tickcolor": af_chart_feature_colour,  # Tick mark colours
+            "tickfont": {
+                "size": base_size,
+            },  # Tick label font size
+            "tickwidth": 1,
+            "ticks": "outside",  # Removes tick marks
+            "title": {  # Axes title
+                "text": None,  # Removes axes title
+                "standoff": half_line / 2,  # Position from axes
+            },
+            "fixedrange": True,  # Disables zoom and pan, keeps range fixed
+            "zeroline": True,  # Makes zeroline visible
+            "zerolinecolor": af_chart_feature_colour,  # Zero line colour
+        },
+        "yaxis": {  # Configures the y-axis (as with the x-axis above)
+            "automargin": True,
+            "gridcolor": af_chart_feature_colour,
+            "linecolor": af_chart_feature_colour,
+            "linewidth": 1,
+            "tickcolor": af_chart_feature_colour,
+            "tickfont": {"size": base_size},
+            "tickwidth": 1,
+            "ticks": "outside",
+            "title": {
+                "text": None,
+                "standoff": half_line / 2,  # Position from axes
+            },
+            "fixedrange": True,
+            "zeroline": True,
+            "zerolinecolor": af_chart_feature_colour,
+        },
+    },
+    data={"scatter": [{"marker": {"size": 12}, "line": {"width": 2.5}}]},
+)

afcharts-1.0.0a0/src/afcharts.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: afcharts
+Version: 1.0.0a0
+Summary: A python package to produce charts following UK Government Analysis Function guidance
+Author: Crown Copyright
+Maintainer-email: Nick Henden <Nick.Henden@ukhsa.gov.uk>, Tom Farley <tom.farley@ukhsa.gov.uk>, Stelios Georgiou <Stelios.Georgiou@ukhsa.gov.uk>, Frederico Rodrigues <fred.rodrigues@defra.gov.uk>, Peter Brohan <peter.brohan@communities.gov.uk>, Fahim Hossain <fahim.hossain@ukhsa.gov.uk>
+Project-URL: Homepage, https://github.com/best-practice-and-impact/afcharts-py
+Project-URL: Documentation, https://best-practice-and-impact.github.io/afcharts-py/
+Project-URL: Source, https://github.com/best-practice-and-impact/afcharts-py
+Project-URL: Issue Tracker, https://github.com/best-practice-and-impact/afcharts-py/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: plotly>=6.1.2
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: PyYAML>=5.0
+Dynamic: license-file
+
+
+# afcharts-py <img src="docs/images/logo.svg" alt="afcharts logo" align="right" height="150"/>
+
+## Overview
+
+The afcharts python package helps make accessible Matplotlib and Plotly charts following [Government Analysis Function Data Visualisation guidance](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-charts/):
+
+- **Automatic chart formatting** with pre-built style sheets for Matplotlib and Plotly
+- **Chart colours** from the Analysis Function [accessible colour palettes](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-4)
+- **Example code** for common chart types in the [cookbook](https://best-practice-and-impact.github.io/afcharts-py/)
+
+Looking for the R version? Check out the [afcharts R package](https://best-practice-and-impact.github.io/afcharts/).
+
+<img src="docs/images/example_charts/bar_chart-matplotlib_afcharts.png" width="28.1%" alt="A grouped bar chart in afcharts style showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/scatterplot-matplotlib_afcharts.png" width="30%" alt="A scatterplot in afcharts style showing life expectancy against GDP per capita for 142 countries in 2007."/> <img src="docs/images/example_charts/line_chart-matplotlib_afcharts.png" width="37.5%" alt="A line chart in afcharts style showing life expectancy in China and the UK from 1952 to 2007"/>
+
+## Installation
+
+afcharts is available at the Python Package Index (PyPI):
+```bash
+pip install afcharts
+```
+or see the [alternative installation](https://best-practice-and-impact.github.io/afcharts-py/getting-started.html) instructions.
+
+## Usage
+
+Format any Matplotlib or Plotly chart in the Analysis Function style using the built-in style sheets.
+
+See the [Getting Started](https://best-practice-and-impact.github.io/afcharts-py/getting-started.html) guide for more options and the [cookbook](https://best-practice-and-impact.github.io/afcharts-py/) for extensive examples.
+
+### Matplotlib
+
+```python
+import matplotlib.pyplot as plt
+
+# Apply the afcharts style to all Matplotlib plots
+plt.style.use('afcharts.afcharts')
+```
+
+Example: A [Matplotlib bar chart](https://best-practice-and-impact.github.io/afcharts-py/01-matplotlib-usage.html#grouped-bar-chart) with afcharts (left) and without (right)
+
+<img src="docs/images/example_charts/bar_chart-matplotlib_afcharts.png" width="35%" alt="Grouped bar chart (afcharts style) showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/bar_chart-matplotlib_default.png" width="34.7%" alt="Grouped bar chart (default Matplotlib) showing life expectancy in 1967 and 2007 for four countries. Bars: blue for 1967, orange for 2007."/>
+
+### Plotly
+
+```python
+from afcharts.pio_template import pio
+
+# Apply the afcharts style to all Plotly plots
+pio.templates.default = "afcharts"
+```
+
+Example: A [Plotly bar chart](https://best-practice-and-impact.github.io/afcharts-py/03-plotly-usage.html#grouped-bar-chart) with afcharts (left) and without (right)
+
+<img src="docs/images/example_charts/bar_chart-plotly_afcharts.png" width="35%" alt="Grouped bar chart (afcharts style) showing life expectancy in 1967 and 2007 for four countries. Bars use Analysis Function palette: dark blue for 1967, orange for 2007."/> <img src="docs/images/example_charts/bar_chart-plotly_default.png" width="35%" alt="Grouped bar chart (default Plotly) showing life expectancy in 1967 and 2007 for four countries. Bars: blue for 1967, red for 2007."/>
+
+### Colours
+
+Easily return a list of colours from any of the Analysis Function [accessible colour palettes](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-4) with the `get_af_colours()` function:
+
+```python
+from afcharts.af_colours import get_af_colours
+
+# Get the duo colour palette hex codes
+duo = get_af_colours("duo")
+```
+
+## Getting help
+If you encounter a bug, please file a minimal reproducible example on [Github Issues](https://github.com/best-practice-and-impact/afcharts-py/issues). For questions and other discussion, please start a [discussion](https://github.com/best-practice-and-impact/afcharts-py/discussions).
+
+## Contributing
+Interested in contributing? Check out the [contributing guidelines](CONTRIBUTING.md). 
+
+## Acknowledgments
+The afcharts python package is based on the
+[afcharts](https://github.com/best-practice-and-impact/afcharts.git) R package and the [py-af-colours](https://github.com/best-practice-and-impact/py-af-colours) package.
+
+## License
+Unless stated otherwise, the codebase is released under [the MIT License](LICENSE.md). This covers both the codebase and any sample code in the documentation.
+
+The documentation is [© Crown copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government 3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) licence.

afcharts-1.0.0a0/src/afcharts.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE.md
+README.md
+pyproject.toml
+src/afcharts/__init__.py
+src/afcharts/af_colours.py
+src/afcharts/afcharts.mplstyle
+src/afcharts/pio_template.py
+src/afcharts.egg-info/PKG-INFO
+src/afcharts.egg-info/SOURCES.txt
+src/afcharts.egg-info/dependency_links.txt
+src/afcharts.egg-info/requires.txt
+src/afcharts.egg-info/top_level.txt
+src/afcharts/assets/__init__.py
+src/afcharts/config/af_colours.yaml

afcharts-1.0.0a0/src/afcharts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

afcharts-1.0.0a0/src/afcharts.egg-info/requires.txt

@@ -0,0 +1,4 @@
+matplotlib>=3.10.3
+plotly>=6.1.2
+typeguard>=4.4.4
+PyYAML>=5.0

afcharts-1.0.0a0/src/afcharts.egg-info/top_level.txt

@@ -0,0 +1 @@
+afcharts