dashiyaml 0.0.2__tar.gz

dashiyaml-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corentin Dupriez
+
+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.

dashiyaml-0.0.2/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: dashiyaml
+Version: 0.0.2
+Summary: Dashboard as code tool - turn YAML configs into standalone HTML dashboards
+Author: Corentin Dupriez
+License: MIT
+Project-URL: Homepage, https://github.com/Corentin-dupriez/dashi
+Project-URL: Bug Tracker, https://github.com/Corentin-dupriez/dashi/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: polars
+Requires-Dist: plotly
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: jinja2
+Requires-Dist: typer
+Requires-Dist: duckdb
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == "postgres"
+Dynamic: license-file
+
+# dashi
+
+dashi is a dashboard-as-code application that allows you to create dashboards
+from yaml files. It used Polars for fast and efficient dataframe processing,
+and Plotly for visualisation.
+
+## Status
+
+⚠️ dashi is currently in early development.
+The API and configuration format may change.
+
+## Philosophy
+
+dashi follows a **dashboard-as-code** approach.
+
+Instead of building dashboards through a GUI, dashboards are defined
+as YAML files that can be versioned, reviewed, and deployed like code.
+
+This allows dashboards to be:
+
+- version controlled
+- reproducible
+- easy to review in pull requests
+
+## How to use
+
+### Install Dashi
+
+First, make sure Python 3.9 or above is installed:
+`python --version`
+
+Install dashi from Pypi:
+`pip install dashiyaml`
+
+For PostgreSQL datasource support, install the optional extra:
+`pip install dashi[postgres]`
+
+### Initialize folder structure
+
+After having cloned the repo and installed dependencies, you can initiate the
+folder structure with
+
+`dashi init`
+
+This will create the following structure (if it doesn't already exist)
+
+```txt
++ data_sources
++ staging_data
++ templates
+  + dashboard_template.html
++ builds
+  + static
+    + style.css
+```
+
+### Configuring data sources
+
+The first step of creating visualisations is done by defining data sources.
+This should be done in the data_sources folder as a yaml file. This file
+should contain the parametrization listed below.
+
+#### Csv and JSON datasources
+
+Csv and JSON
+
+```yaml
+datasources:
+  - name: sample_data
+    type: csv
+    columns:
+      - name: id
+        type: integer
+      - name: name
+        type: string
+```
+
+For the moment, only the csv, json, duckdb and PostgreSQL datasource types are supported,
+but more formats will be supported soon.
+The datasource name must match the filename (without the extension)
+of the data file stored in the `staging_data` folder.
+When using the `dashi build` command, dashi
+will then look within the staging_data folder, and generate a polars dataframe
+by using the defined schema.
+
+### Configuring the dashboards
+
+Once the datasources are defined, the dashboard itself can be defined within the
+`dashboards` folder as a yaml file. Each yaml file should correspond to
+one dashboard, but each dashboard is composed of several charts.
+The file should contain the dashboard name, as well as a list of charts.
+Each chart should be defined with:
+
+- title
+- chart type (ex: line, bar)
+- datasource (corresponding to a datasource defined in `data_sources`)
+- x (corresponding to a column defined for the datasource)
+- y (corresponding to a column defined for the datasource)
+- options: allow a pass through of plotly options to the widget. For example:
+  - theme
+  - title
+  - font
+- transforms: contains instructions on transformation of the data before plotting.
+This includes:
+  - group by
+  - sum
+  - average
+  - count
+
+All the options that can be passed can be seen [on the Plotly documentation](https://plotly.com/python/reference/layout/)
+
+```yaml
+dashboard: 
+  title: sample_dashboard
+
+  charts: 
+    - name: sample_chart
+      type: bar
+      datasource: sample_data
+      x: channel
+      y: orders
+      options: 
+        title: Orders by channel
+        template: plotly_white
+      transform:
+        groupby: channel
+        metrics:
+          orders: sum
+
+```
+
+### dashi build
+
+Once both datasources and dashboards have been defined, the `dashi build`
+command can be used to create the dashboards based on the provided definitions.
+
+This command will create html files under the `builds` folder.
+
+WARNING: `dashi build` will override previous version of the dashboards
+you have already exported
+
+### dashi serve
+
+The command `dashi serve` will create a simple http server on the port 8000
+by default. The created dashboards can be accessed from there.
+
+### dashi clean
+
+If you wish to clean up the created dashboards, you can use the `dashi clean` command.
+It will delete every html file within the `builds` folder

dashiyaml-0.0.2/README.md

@@ -0,0 +1,150 @@
+# dashi
+
+dashi is a dashboard-as-code application that allows you to create dashboards
+from yaml files. It used Polars for fast and efficient dataframe processing,
+and Plotly for visualisation.
+
+## Status
+
+⚠️ dashi is currently in early development.
+The API and configuration format may change.
+
+## Philosophy
+
+dashi follows a **dashboard-as-code** approach.
+
+Instead of building dashboards through a GUI, dashboards are defined
+as YAML files that can be versioned, reviewed, and deployed like code.
+
+This allows dashboards to be:
+
+- version controlled
+- reproducible
+- easy to review in pull requests
+
+## How to use
+
+### Install Dashi
+
+First, make sure Python 3.9 or above is installed:
+`python --version`
+
+Install dashi from Pypi:
+`pip install dashiyaml`
+
+For PostgreSQL datasource support, install the optional extra:
+`pip install dashi[postgres]`
+
+### Initialize folder structure
+
+After having cloned the repo and installed dependencies, you can initiate the
+folder structure with
+
+`dashi init`
+
+This will create the following structure (if it doesn't already exist)
+
+```txt
++ data_sources
++ staging_data
++ templates
+  + dashboard_template.html
++ builds
+  + static
+    + style.css
+```
+
+### Configuring data sources
+
+The first step of creating visualisations is done by defining data sources.
+This should be done in the data_sources folder as a yaml file. This file
+should contain the parametrization listed below.
+
+#### Csv and JSON datasources
+
+Csv and JSON
+
+```yaml
+datasources:
+  - name: sample_data
+    type: csv
+    columns:
+      - name: id
+        type: integer
+      - name: name
+        type: string
+```
+
+For the moment, only the csv, json, duckdb and PostgreSQL datasource types are supported,
+but more formats will be supported soon.
+The datasource name must match the filename (without the extension)
+of the data file stored in the `staging_data` folder.
+When using the `dashi build` command, dashi
+will then look within the staging_data folder, and generate a polars dataframe
+by using the defined schema.
+
+### Configuring the dashboards
+
+Once the datasources are defined, the dashboard itself can be defined within the
+`dashboards` folder as a yaml file. Each yaml file should correspond to
+one dashboard, but each dashboard is composed of several charts.
+The file should contain the dashboard name, as well as a list of charts.
+Each chart should be defined with:
+
+- title
+- chart type (ex: line, bar)
+- datasource (corresponding to a datasource defined in `data_sources`)
+- x (corresponding to a column defined for the datasource)
+- y (corresponding to a column defined for the datasource)
+- options: allow a pass through of plotly options to the widget. For example:
+  - theme
+  - title
+  - font
+- transforms: contains instructions on transformation of the data before plotting.
+This includes:
+  - group by
+  - sum
+  - average
+  - count
+
+All the options that can be passed can be seen [on the Plotly documentation](https://plotly.com/python/reference/layout/)
+
+```yaml
+dashboard: 
+  title: sample_dashboard
+
+  charts: 
+    - name: sample_chart
+      type: bar
+      datasource: sample_data
+      x: channel
+      y: orders
+      options: 
+        title: Orders by channel
+        template: plotly_white
+      transform:
+        groupby: channel
+        metrics:
+          orders: sum
+
+```
+
+### dashi build
+
+Once both datasources and dashboards have been defined, the `dashi build`
+command can be used to create the dashboards based on the provided definitions.
+
+This command will create html files under the `builds` folder.
+
+WARNING: `dashi build` will override previous version of the dashboards
+you have already exported
+
+### dashi serve
+
+The command `dashi serve` will create a simple http server on the port 8000
+by default. The created dashboards can be accessed from there.
+
+### dashi clean
+
+If you wish to clean up the created dashboards, you can use the `dashi clean` command.
+It will delete every html file within the `builds` folder

dashiyaml-0.0.2/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dashiyaml"
+version = "0.0.2"
+description = "Dashboard as code tool - turn YAML configs into standalone HTML dashboards"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Corentin Dupriez" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Visualization",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "polars",
+  "plotly",
+  "numpy",
+  "pyyaml",
+  "jinja2",
+  "typer",
+  "duckdb",
+]
+
+[project.optional-dependencies]
+postgres = ["psycopg2-binary"]
+
+[project.urls]
+Homepage = "https://github.com/Corentin-dupriez/dashi"
+"Bug Tracker" = "https://github.com/Corentin-dupriez/dashi/issues"
+
+[project.scripts]
+dashi = "dashi.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["dashi*"]
+exclude = ["tests*"]

dashiyaml-0.0.2/setup.cfg

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

dashiyaml-0.0.2/src/dashi/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

dashiyaml-0.0.2/src/dashi/charts/__init__.py

@@ -0,0 +1,6 @@
+from .bar import BarChart
+from .line import LineChart
+from .pie import PieChart
+from .chart import BaseChart
+from .scatter import ScatterChart
+from .registry import CHARTS

dashiyaml-0.0.2/src/dashi/charts/bar.py

@@ -0,0 +1,18 @@
+from .chart import BaseChart
+import plotly.express as px
+import polars as pl
+
+
+class BarChart(BaseChart):
+    def build(
+        self,
+        chart_name: str,
+        df: pl.DataFrame,
+        x: str,
+        y: str,
+        options: dict[str, str] | None = None,
+    ):
+        fig = px.bar(data_frame=df, x=x, y=y, title=chart_name)
+        if options is not None:
+            self.update_layout(fig, options)
+        return fig

dashiyaml-0.0.2/src/dashi/charts/chart.py

@@ -0,0 +1,23 @@
+import polars as pl
+from abc import ABC
+
+
+class BaseChart(ABC):
+    def build(
+        self,
+        chart_name: str,
+        df: pl.DataFrame,
+        x: str,
+        y: str,
+        options: dict[str, str] | None,
+    ):
+        raise NotImplementedError
+
+    def update_layout(self, fig, options: dict):
+        try:
+            fig.update_layout(**options)
+            return fig
+        except ValueError:
+            raise ValueError(
+                "One of the options provided in the chart definition is incorrect"
+            )

dashiyaml-0.0.2/src/dashi/charts/line.py

@@ -0,0 +1,18 @@
+from .chart import BaseChart
+import polars as pl
+import plotly.express as px
+
+
+class LineChart(BaseChart):
+    def build(
+        self,
+        chart_name: str,
+        df: pl.DataFrame,
+        x: str,
+        y: str,
+        options: dict[str, str] | None = None,
+    ):
+        fig = px.line(df, x=x, y=y, title=chart_name)
+        if options is not None:
+            self.update_layout(fig, options)
+        return fig

dashiyaml-0.0.2/src/dashi/charts/pie.py

@@ -0,0 +1,20 @@
+import plotly.express as px
+import polars as pl
+
+from .chart import BaseChart
+
+
+class PieChart(BaseChart):
+    def build(
+        self,
+        chart_name: str,
+        df: pl.DataFrame,
+        x: str,
+        y: str,
+        options: dict[str, str] | None = None,
+    ):
+        fig = px.pie(data_frame=df, values=x, names=y, title=chart_name)
+        if options is not None:
+            fig = fig.update_layout(options)
+
+        return fig

dashiyaml-0.0.2/src/dashi/charts/registry.py

@@ -0,0 +1,13 @@
+from .pie import PieChart
+from .table import Table
+from .bar import BarChart
+from .line import LineChart
+from .scatter import ScatterChart
+
+CHARTS = {
+    "line": LineChart(),
+    "bar": BarChart(),
+    "pie": PieChart(),
+    "scatter": ScatterChart(),
+    "table": Table(),
+}

dashiyaml-0.0.2/src/dashi/charts/scatter.py

@@ -0,0 +1,19 @@
+import plotly.express as px
+import polars as pl
+
+from .chart import BaseChart
+
+
+class ScatterChart(BaseChart):
+    def build(
+        self,
+        chart_name: str,
+        df: pl.DataFrame,
+        x: str,
+        y: str,
+        options: dict[str, str] | None = None,
+    ):
+        fig = px.scatter(df, x=x, y=y, title=chart_name)
+        if options is not None:
+            self.update_layout(fig, options)
+        return fig

dashiyaml-0.0.2/src/dashi/charts/table.py

@@ -0,0 +1,13 @@
+import polars as pl
+from plotly import graph_objects as go
+from typing import List
+
+
+class Table:
+    def build(self, title: str, df: pl.DataFrame, columns: List[str]) -> go.Figure:
+        headers = [col for col in df.columns if col in columns]
+        data = [col for col in df.select(headers).to_dict(as_series=False).values()]
+        table = go.Figure(
+            data=go.Table(header=dict(values=headers), cells=dict(values=data))
+        )
+        return table

dashiyaml-0.0.2/src/dashi/cli.py

@@ -0,0 +1,61 @@
+import typer
+import plotly.io as pio
+
+from .structure.cleaner import clean_builds
+from .datasources import Datasources
+from .dashboard import Dashboard
+from .render import render_dashboard
+from .serve import serve as serve_dashboard
+from .structure.initializer import (
+    create_dashboard_template,
+    structure_already_present,
+    create_structure,
+)
+
+app = typer.Typer()
+
+
+@app.command()
+def init() -> None:
+    """
+    Initializes dashi folder structure.
+    If the structure is already present, it will be skipped.
+    After creating the structure, creates the dashboard template, which will be used to generate new dashboards.
+    """
+    if not structure_already_present():
+        create_structure()
+    else:
+        print("Structure is already present, skipping creation")
+
+    create_dashboard_template()
+
+
+@app.command()
+def build() -> None:
+    data_sources = Datasources()
+    dashboard = Dashboard(data_sources)
+    charts = [
+        {"id": f"chart_{i}", "figure": pio.to_json(chart)}
+        for i, chart in enumerate(dashboard.charts)
+    ]
+    render_dashboard(dashboard, charts)
+
+
+@app.command()
+def serve() -> None:
+    """
+    Creates a simple server to display the generated dashboards
+    """
+    serve_dashboard()
+
+
+@app.command()
+def clean() -> None:
+    """
+    Cleans the dashboard folder from the generated dashboards.
+    """
+    clean_builds()
+
+
+if __name__ == "__main__":
+    app()

dashiyaml-0.0.2/src/dashi/config/__init__.py

@@ -0,0 +1 @@
+from .yaml_parser import parse_yaml, NoConfigFile

dashiyaml-0.0.2/src/dashi/config/yaml_parser.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+from typing import Any
+import yaml
+
+try:
+    from yaml import CLoader as Loader, CDumper as Dumper
+except ImportError:
+    from yaml import Loader, Dumper
+
+
+class NoConfigFile(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__()
+
+
+def parse_yaml(file_path: Path, file_type: str) -> dict:
+    """
+    Parses the yaml files in the provided file_path and returns their content as a dict
+    Args:
+        file_path: a Path object representing the folder to parse
+        file_type: the type of file parsed, which is used for the function to
+            return the sub-dictionnary with the actual content
+    Returns:
+        a dictionnary representing the content of the yaml file
+    """
+    files: list = list(file_path.glob("*.y*ml"))
+
+    if not files:
+        raise NoConfigFile(f"No YAML config found in {file_path}")
+
+    file = files[0]
+    with open(file, "r") as f:
+        config: dict[Any, Any] | None = yaml.load(f, Loader=Loader)
+
+    if config is None:
+        raise ValueError(f"{file} is empty")
+    try:
+        return config[file_type]
+    except KeyError:
+        raise ValueError(
+            "There is a problem with the datasource file (the format is incorrect)"
+        )