piholelongtermstats 0.2.4__tar.gz → 0.2.6__tar.gz

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: piholelongtermstats
-Version: 0.2.4
+Version: 0.2.6
 Summary: A dashboard to explore long-term DNS query data from Pi-hole FTL database files.
 Author-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
 Maintainer-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
@@ -22,11 +22,10 @@ Provides-Extra: develop
 Requires-Dist: pytest==9.0.1; extra == "develop"
 Requires-Dist: ruff; extra == "develop"
 Requires-Dist: build==1.3.0; extra == "develop"
-Requires-Dist: twine==6.2.0; extra == "develop"
 Requires-Dist: pytest-cov==7.0.0; extra == "develop"
 Dynamic: license-file
 
-# Pi Hole Long Term Statistics v.0.2.4
+# Pi Hole Long Term Statistics v.0.2.6
 
 <div align="center">
 
@@ -74,11 +73,13 @@ See more [screenshots](https://github.com/davistdaniel/PiHoleLongTermStats/blob/
 > Using your actual Pi-hole FTL db file for querying is **not** recommended and it is advised to use a copy. Place the copy in the project root or specify its path using the `--db_path` argument or `PIHOLE_LT_STATS_DB_PATH` environment variable. In any case, PiHoleLongTermStats does not monitor for changes in the Pi-hole FTL db file even if you mount it.
 
 > [!TIP]
-> * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the live database. Use the reload button in the dashboard to refresh the stats.
+> * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the actual database. Use the reload button in the dashboard to refresh the stats.
 > * Set your timezone (e.g "Europe/Berlin") using `--timezone` or `PIHOLE_LT_STATS_TIMEZONE`.
 
 > [!IMPORTANT]
-> * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the dashboard is refreshed or the reload button is clicked.
+> * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the the reload button is clicked.
+> * Refreshing the page uing the browser's refresh button, will always serve cached dashboard and data.
+> * To update the dashboard with newer data from the database, you have to **manually** click the reload button (🔄) in the dashboard. Alternatively, you can restart the script or the docker container (using a cron job, for instance).
 > * If no date range is selected, it uses the default period set by `--days` or `PIHOLE_LT_STATS_DAYS`.
 > * Large date ranges may lead to increased memory usage.
 > * When multiple database files are provided, PiHoleLongTermStats concatenates them into a single dataframe and sorts the combined data by timestamp. Duplicate entries are **not** removed for calculating stats. Consolidating multiple databases can lead to increased memory usage.
@@ -104,7 +105,7 @@ If you have a copy of your `pihole-FTL.db` file, you can quickly run the dashboa
 
    ```bash
    # Example: Copy from the default Pi-hole location
-   sudo cp /etc/pihole/pihole-FTL.db . 
+   sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db" 
    # Ensure the user running the app has read permissions
    sudo chown $USER:$USER pihole-FTL.db
    ```
@@ -176,7 +177,7 @@ If installing using python, you can install from this git repo or as a package f
 
    ```bash
    # Example: Copy from the default Pi-hole location
-   sudo cp /etc/pihole/pihole-FTL.db . 
+   sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db"
    # Ensure the user running the app has read permissions
    sudo chown $USER:$USER pihole-FTL.db
    ```
@@ -231,7 +232,7 @@ If installing using python, you can install from this git repo or as a package f
 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
     ```bash
     # Example: Copy from the default Pi-hole location
-    sudo cp /etc/pihole/pihole-FTL.db . 
+    sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db"
     # Ensure the user running the app has read permissions
     sudo chown $USER:$USER pihole-FTL.db 
     ```
@@ -285,6 +286,7 @@ You can configure the application using command-line arguments or environment va
 ## 🧑‍💻 Contributing
 
 Any contribution, feature ideas or bug fixes are always welcome.
+In case of new features, opening an issue and discussion before implementation is recommended.
 This project uses uv for dependency management.
 
 ### Development workflow

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/README.md

@@ -1,4 +1,4 @@
-# Pi Hole Long Term Statistics v.0.2.4
+# Pi Hole Long Term Statistics v.0.2.6
 
 <div align="center">
 
@@ -46,11 +46,13 @@ See more [screenshots](https://github.com/davistdaniel/PiHoleLongTermStats/blob/
 > Using your actual Pi-hole FTL db file for querying is **not** recommended and it is advised to use a copy. Place the copy in the project root or specify its path using the `--db_path` argument or `PIHOLE_LT_STATS_DB_PATH` environment variable. In any case, PiHoleLongTermStats does not monitor for changes in the Pi-hole FTL db file even if you mount it.
 
 > [!TIP]
-> * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the live database. Use the reload button in the dashboard to refresh the stats.
+> * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the actual database. Use the reload button in the dashboard to refresh the stats.
 > * Set your timezone (e.g "Europe/Berlin") using `--timezone` or `PIHOLE_LT_STATS_TIMEZONE`.
 
 > [!IMPORTANT]
-> * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the dashboard is refreshed or the reload button is clicked.
+> * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the the reload button is clicked.
+> * Refreshing the page uing the browser's refresh button, will always serve cached dashboard and data.
+> * To update the dashboard with newer data from the database, you have to **manually** click the reload button (🔄) in the dashboard. Alternatively, you can restart the script or the docker container (using a cron job, for instance).
 > * If no date range is selected, it uses the default period set by `--days` or `PIHOLE_LT_STATS_DAYS`.
 > * Large date ranges may lead to increased memory usage.
 > * When multiple database files are provided, PiHoleLongTermStats concatenates them into a single dataframe and sorts the combined data by timestamp. Duplicate entries are **not** removed for calculating stats. Consolidating multiple databases can lead to increased memory usage.
@@ -76,7 +78,7 @@ If you have a copy of your `pihole-FTL.db` file, you can quickly run the dashboa
 
    ```bash
    # Example: Copy from the default Pi-hole location
-   sudo cp /etc/pihole/pihole-FTL.db . 
+   sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db" 
    # Ensure the user running the app has read permissions
    sudo chown $USER:$USER pihole-FTL.db
    ```
@@ -148,7 +150,7 @@ If installing using python, you can install from this git repo or as a package f
 
    ```bash
    # Example: Copy from the default Pi-hole location
-   sudo cp /etc/pihole/pihole-FTL.db . 
+   sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db"
    # Ensure the user running the app has read permissions
    sudo chown $USER:$USER pihole-FTL.db
    ```
@@ -203,7 +205,7 @@ If installing using python, you can install from this git repo or as a package f
 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
     ```bash
     # Example: Copy from the default Pi-hole location
-    sudo cp /etc/pihole/pihole-FTL.db . 
+    sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db"
     # Ensure the user running the app has read permissions
     sudo chown $USER:$USER pihole-FTL.db 
     ```
@@ -257,6 +259,7 @@ You can configure the application using command-line arguments or environment va
 ## 🧑‍💻 Contributing
 
 Any contribution, feature ideas or bug fixes are always welcome.
+In case of new features, opening an issue and discussion before implementation is recommended.
 This project uses uv for dependency management.
 
 ### Development workflow

piholelongtermstats-0.2.6/piholelongtermstats/__init__.py

@@ -0,0 +1,3 @@
+## Author :  Davis T. Daniel
+## PiHoleLongTermStats v.0.2.5
+## License :  MIT

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats/app.py

@@ -1,7 +1,8 @@
 ## Author :  Davis T. Daniel
-## PiHoleLongTermStats v.0.2.4
+## PiHoleLongTermStats v.0.2.6
 ## License :  MIT
 
+
 import os
 import gc
 import argparse
@@ -11,6 +12,7 @@ import plotly.express as px
 import pandas as pd
 from dash import Dash, dcc, html, Input, Output, State
 from zoneinfo import ZoneInfo
+from datetime import datetime
 
 from piholelongtermstats.db import read_pihole_ftl_db, connect_to_sql, probe_sample_df
 from piholelongtermstats.process import (
@@ -23,9 +25,11 @@ from piholelongtermstats.plot import (
     generate_plot_data,
     generate_client_activity_over_time,
     generate_queries_over_time,
+    generate_top_blocked_domains,
+    generate_top_allowed_domains,
 )
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 
 # logging setup
 logging.basicConfig(
@@ -169,6 +173,8 @@ def serve_layout(
                 f"Removed domains matching the regex pattern : {pattern}, number of rows in dataframe : {len(df)}"
             )
 
+    last_refresh_time = datetime.now(ZoneInfo(timezone)).strftime("%d-%m-%Y (%H:%M)")
+
     # should reduce some memory consumption
     df["id"] = df["id"].astype("int32")
     df["type"] = df["type"].astype("int8")
@@ -189,6 +195,10 @@ def serve_layout(
     callback_data = {
         "hourly_agg": hourly_data["hourly_agg"],
         "top_clients": hourly_data["top_clients"],
+        "blocked_df": plot_data["blocked_df"],
+        "allowed_df": plot_data["allowed_df"],
+        "blocked_df_by_client": plot_data["blocked_df_by_client"],
+        "allowed_df_by_client": plot_data["allowed_df_by_client"],
         "data_span_days": plot_data["data_span_days"],
     }
 
@@ -197,7 +207,6 @@ def serve_layout(
     gc.collect()
 
     # generate initial plots
-
     initial_filtered_fig = generate_queries_over_time(
         callback_data=callback_data, client=None
     )
@@ -249,11 +258,19 @@ def serve_layout(
                     ),
                     html.Br(),
                     html.H6(
-                        f"Timezone is {timezone}. Database records begin on {stats['oldest_data_point']} and end on {stats['latest_data_point']}."
+                        f"Timezone is {timezone}. Database records begin on {stats['oldest_data_point']} and end on {stats['latest_data_point']}. The dashboard was last reloaded on {last_refresh_time}."
                     ),
                 ],
                 className="sub-heading-card",
             ),
+            html.Div(
+                [
+                    html.Hr(),
+                    html.Span("Info Cards"),
+                    html.Hr(),
+                ],
+                className="section-divider",
+            ),
             # info cards
             html.Div(
                 [
@@ -631,12 +648,12 @@ def serve_layout(
                                     html.H3("Longest Idle Period"),
                                     html.P(
                                         f"{stats['max_idle_ms']:,.0f} s"
-                                        if stats['max_idle_ms'] is not None
+                                        if stats["max_idle_ms"] is not None
                                         else "N/A"
                                     ),
                                     html.P(
                                         f"Between {stats['before_gap']} and {stats['after_gap']}"
-                                        if stats['before_gap'] and stats['after_gap']
+                                        if stats["before_gap"] and stats["after_gap"]
                                         else "N/A",
                                         style={"fontSize": "14px", "color": "#777"},
                                     ),
@@ -659,7 +676,7 @@ def serve_layout(
                                     ),
                                     html.P(
                                         f"Avg reply time: {stats['slowest_avg_reply_time'] * 1000:.2f} ms"
-                                        if stats['slowest_avg_reply_time']
+                                        if stats["slowest_avg_reply_time"]
                                         else "N/A",
                                         style={"fontSize": "14px", "color": "#777"},
                                     ),
@@ -704,32 +721,63 @@ def serve_layout(
                 ],
                 className="kpi-container",
             ),
+            html.Div(
+                [
+                    html.Hr(),
+                    html.Span("Queries and domains"),
+                    html.Hr(),
+                ],
+                className="section-divider",
+            ),
             html.Br(),
             html.Div(
                 [
-                    html.H2("Queries over time"),
-                    html.H5("Queries from all clients. The data is aggregated hourly."),
-                    dcc.Dropdown(
-                        options=[
-                            {"label": c, "value": c} for c in plot_data["client_list"]
+                    html.Div(
+                        [
+                            dcc.Dropdown(
+                                options=[
+                                    {"label": c, "value": c}
+                                    for c in plot_data["client_list"]
+                                ],
+                                id="client-filter",
+                                placeholder="Select a Client",
+                            ),
                         ],
-                        id="client-filter",
-                        placeholder="Select a Client",
+                        className="cardplot",
                     ),
-                    dcc.Graph(id="filtered-view", figure=initial_filtered_fig),
-                    html.H2("Client Activity Over Time"),
-                    html.H5(
-                        "Client acitivity for all clients. The data is aggregated hourly."
+                    html.Br(),
+                    html.Div(
+                        [
+                            html.H2("Queries over time"),
+                            html.H5(
+                                "Queries from all or selected clients. The data is aggregated hourly."
+                            ),
+                            dcc.Graph(id="filtered-view", figure=initial_filtered_fig),
+                        ],
+                        className="cardplot",
                     ),
-                    dcc.Graph(id="client-activity-view", figure=initial_activity_fig),
-                ],
-                className="cardplot",
+                    html.Br(),
+                    html.Div(
+                        [
+                            html.H2("Client Activity Over Time"),
+                            html.H5(
+                                "Client acitivity for all or selected clients. The data is aggregated hourly."
+                            ),
+                            dcc.Graph(
+                                id="client-activity-view", figure=initial_activity_fig
+                            ),
+                        ],
+                        className="cardplot",
+                    ),
+                ]
             ),
             html.Br(),
             html.Div(
                 [
                     html.H2("Top Blocked Domains"),
-                    html.H5(f"Top {args.n_domains} blocked domains."),
+                    html.H5(
+                        f"Top {args.n_domains} blocked domains. Client filter (see above) can be used to select a specific client."
+                    ),
                     dcc.Graph(
                         id="top-blocked-domains",
                         figure=px.bar(
@@ -755,10 +803,13 @@ def serve_layout(
                 ],
                 className="cardplot",
             ),
+            html.Br(),
             html.Div(
                 [
                     html.H2("Top Allowed Domains"),
-                    html.H5(f"Top {args.n_domains} allowed domains."),
+                    html.H5(
+                        f"Top {args.n_domains} allowed domains. Client filter (see above) can be used to select a specific client."
+                    ),
                     dcc.Graph(
                         id="top-allowed-domains",
                         figure=px.bar(
@@ -785,6 +836,15 @@ def serve_layout(
                 className="cardplot",
             ),
             html.Br(),
+            html.Div(
+                [
+                    html.Hr(),
+                    html.Span("Activity"),
+                    html.Hr(),
+                ],
+                className="section-divider",
+            ),
+            html.Br(),
             html.Div(
                 [
                     html.H2("Top Client Activity"),
@@ -945,6 +1005,15 @@ def serve_layout(
                 className="cardplot",
             ),
             html.Br(),
+            html.Div(
+                [
+                    html.Hr(),
+                    html.Span("Reply times"),
+                    html.Hr(),
+                ],
+                className="section-divider",
+            ),
+            html.Br(),
             html.Div(
                 [
                     html.Div(
@@ -972,6 +1041,34 @@ def serve_layout(
                 ]
             ),
             html.Br(),
+            html.Div(
+                [
+                    html.Div(
+                        [
+                            html.H2("Reply Time Distribution"),
+                            html.H5("Distribution of reply times in milliseconds."),
+                            dcc.Graph(
+                                id="reply-time-histogram",
+                                figure=px.histogram(
+                                    plot_data["reply_time_df"],
+                                    x="reply_time_ms",
+                                    labels={
+                                        "reply_time_ms": "Reply Time (ms)",
+                                    },
+                                    color_discrete_sequence=["#3b82f6"],
+                                    template="plotly_white",
+                                ).update_layout(
+                                    xaxis_title="Reply Time (ms)",
+                                    yaxis_title="Count",
+                                    bargap=0.05,
+                                ),
+                            ),
+                        ],
+                        className="cardplot",
+                    )
+                ]
+            ),
+            html.Br(),
             html.Footer(
                 f"PiHoleLongTermStats v.{__version__}",
                 style={"textAlign": "center", "padding": "10px", "color": "#666"},
@@ -1032,22 +1129,37 @@ PHLTS_CALLBACK_DATA, initial_layout = serve_layout(
 
 logging.info("Setting initial layout...")
 
-app.layout = html.Div(
-    [
-        dcc.Loading(
-            id="loading-main",
-            type="graph",
-            fullscreen=True,
-            children=[
-                html.Div(
-                    id="page-container",
-                    children=initial_layout.children,
-                    className="container",
-                )
-            ],
-        )
-    ]
-)
+# Holds the most recently generated page-container children
+PHLTS_PAGE_CONTAINER_CHILDREN = initial_layout.children
+
+
+def serve_app_layout():
+    """Returns the current app layout.
+
+    Dash calls this function on every full page load/browser refresh (since
+    app.layout is set to a function rather than a static object), so it
+    always reflects the latest data instead of only what existed when the
+    container started.
+    """
+    return html.Div(
+        [
+            dcc.Loading(
+                id="loading-main",
+                type="graph",
+                fullscreen=True,
+                children=[
+                    html.Div(
+                        id="page-container",
+                        children=PHLTS_PAGE_CONTAINER_CHILDREN,
+                        className="container",
+                    )
+                ],
+            )
+        ]
+    )
+
+
+app.layout = serve_app_layout
 
 del initial_layout
 gc.collect()
@@ -1061,7 +1173,7 @@ gc.collect()
     prevent_initial_call=True,
 )
 def reload_page(n_clicks, start_date, end_date):
-    global PHLTS_CALLBACK_DATA
+    global PHLTS_CALLBACK_DATA, PHLTS_PAGE_CONTAINER_CHILDREN
 
     logging.info(f"Reload button clicked. Selected date range: {start_date, end_date}")
 
@@ -1101,6 +1213,10 @@ def reload_page(n_clicks, start_date, end_date):
         ignore_domains=args.ignore_domains,
     )
 
+    # Persist the new layout so that a full browser refresh (which calls
+    # serve_app_layout() again) also sees the reloaded data
+    PHLTS_PAGE_CONTAINER_CHILDREN = layout.children
+
     return layout.children
 
 
@@ -1136,6 +1252,31 @@ def update_client_activity(client, n_clicks):
     return fig
 
 
+@app.callback(
+    Output("top-blocked-domains", "figure"),
+    Output("top-allowed-domains", "figure"),
+    Input("client-filter", "value"),
+    Input("reload-button", "n_clicks"),
+    prevent_initial_call=True,
+)
+def update_top_domains(client, n_clicks):
+    logging.info("Updating top blocked and allowed domain plots...")
+    global PHLTS_CALLBACK_DATA
+
+    blocked_fig = generate_top_blocked_domains(
+        callback_data=PHLTS_CALLBACK_DATA,
+        n_domains=args.n_domains,
+        client=client,
+    )
+    allowed_fig = generate_top_allowed_domains(
+        callback_data=PHLTS_CALLBACK_DATA,
+        n_domains=args.n_domains,
+        client=client,
+    )
+
+    return blocked_fig, allowed_fig
+
+
 def run():
     app.run(host="0.0.0.0", port=args.port, debug=False)
 

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats/assets/style.css

@@ -146,7 +146,6 @@ h3 {
 }
 
 
-
 .cardactivity {
     background: linear-gradient(135deg, #ffffff, #f5f5f0);
     border-radius: 15px;
@@ -344,4 +343,22 @@ h3 {
 .date-picker-btn .dash-datepicker-caret-icon {
     fill: #f7f9fb !important;
     flex-shrink: 0;
+}
+
+.section-divider {
+    display: flex;
+    align-items: center;
+    margin: 20px 0;
+}
+
+.section-divider hr {
+    flex: 1;
+    border: none;
+    border-top: 1px solid #999;
+}
+
+.section-divider span {
+    padding: 0 10px;
+    font-weight: bold;
+    color: #444;
 }

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats/db.py

@@ -1,5 +1,5 @@
 ## Author :  Davis T. Daniel
-## PiHoleLongTermStats v.0.2.4
+## PiHoleLongTermStats v.0.2.6
 ## License :  MIT
 
 import sqlite3

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats/plot.py

@@ -1,5 +1,5 @@
 ## Author :  Davis T. Daniel
-## PiHoleLongTermStats v.0.2.4
+## PiHoleLongTermStats v.0.2.6
 ## License :  MIT
 
 import logging
@@ -8,7 +8,6 @@ import gc
 import plotly.express as px
 import itertools
 
-
 def generate_plot_data(df, n_clients, n_domains):
     """Generate plot data for dashboard visualizations.
     
@@ -71,6 +70,22 @@ def generate_plot_data(df, n_clients, n_domains):
         .rename(columns={"domain": "Domain", "count": "count"})
     )
 
+    blocked_df_by_client = (
+        tmp_blocked.groupby(["client", "domain"]).size().reset_index(name="count")
+    )
+    blocked_df_by_client["Domain"] = blocked_df_by_client["domain"].apply(shorten)
+    blocked_df_by_client = blocked_df_by_client[
+        ["client", "Domain", "count"]
+    ].sort_values(["client", "count"], ascending=[True, False])
+
+    allowed_df_by_client = (
+        tmp_allowed.groupby(["client", "domain"]).size().reset_index(name="count")
+    )
+    allowed_df_by_client["Domain"] = allowed_df_by_client["domain"].apply(shorten)
+    allowed_df_by_client = allowed_df_by_client[
+        ["client", "Domain", "count"]
+    ].sort_values(["client", "count"], ascending=[True, False])
+
     logging.info("Generated plot data for allowed and blocked domains.")
 
     # plot data for reply time over days
@@ -152,6 +167,8 @@ def generate_plot_data(df, n_clients, n_domains):
         "top_clients_stacked": top_clients_stacked,
         "blocked_df": blocked_df,
         "allowed_df": allowed_df,
+        "blocked_df_by_client": blocked_df_by_client,
+        "allowed_df_by_client": allowed_df_by_client,
         "reply_time_df": reply_time_df,
         "client_list": client_list,
         "data_span_days": data_span_days,
@@ -362,3 +379,64 @@ def generate_client_activity_over_time(callback_data, n_clients, client=None):
     gc.collect()
 
     return fig
+
+def generate_top_blocked_domains(callback_data, n_domains, client=None):
+    logging.info("Generating top blocked domains plot...")
+    if client is not None:
+        dff = callback_data.get("blocked_df_by_client", pd.DataFrame()).copy()
+        dff = dff[dff["client"] == client]
+        dff = dff.nlargest(n_domains, "count").reset_index(drop=True)
+        title_txt = f"Domains for {client}"
+    else:
+        dff = callback_data.get("blocked_df", pd.DataFrame()).copy()
+        title_txt = ""
+
+    return _build_top_domain_figure(dff, title_txt, "#ef4444")
+
+
+def generate_top_allowed_domains(callback_data, n_domains, client=None):
+    logging.info("Generating top allowed domains plot...")
+    if client is not None:
+        dff = callback_data.get("allowed_df_by_client", pd.DataFrame()).copy()
+        dff = dff[dff["client"] == client]
+        dff = dff.nlargest(n_domains, "count").reset_index(drop=True)
+        title_txt = f"Domains for {client}"
+    else:
+        dff = callback_data.get("allowed_df", pd.DataFrame()).copy()
+        title_txt = ""
+
+    return _build_top_domain_figure(dff, title_txt, "#10b981")
+
+def _build_top_domain_figure(domain_df, title_txt, color):
+    if domain_df is None or domain_df.empty:
+        fig = px.bar(
+            pd.DataFrame({"Domain": [], "count": []}),
+            x="Domain",
+            y="count",
+            template="plotly_white",
+        )
+        fig.update_layout(
+            title=title_txt,
+            title_font_size=16,
+            showlegend=False,
+            margin=dict(r=0, t=50, l=0, b=0),
+            xaxis=dict(title=None, automargin=True, tickmode="auto"),
+        )
+        return fig
+
+    fig = px.bar(
+        domain_df,
+        y="count",
+        x="Domain",
+        labels={"Domain": "Domain", "count": "Count"},
+        template="plotly_white",
+        color_discrete_sequence=[color],
+    )
+    fig.update_layout(
+        title=title_txt,
+        title_font_size=16,
+        showlegend=False,
+        margin=dict(r=0, t=50, l=0, b=0),
+        xaxis=dict(title=None, automargin=True, tickmode="auto"),
+    )
+    return fig

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats/process.py

@@ -1,5 +1,5 @@
 ## Author :  Davis T. Daniel
-## PiHoleLongTermStats v.0.2.4
+## PiHoleLongTermStats v.0.2.6
 ## License :  MIT
 
 import re

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats/stats.py

@@ -1,5 +1,5 @@
 ## Author :  Davis T. Daniel
-## PiHoleLongTermStats v.0.2.4
+## PiHoleLongTermStats v.0.2.6
 ## License :  MIT
 
 import logging

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: piholelongtermstats
-Version: 0.2.4
+Version: 0.2.6
 Summary: A dashboard to explore long-term DNS query data from Pi-hole FTL database files.
 Author-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
 Maintainer-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
@@ -22,11 +22,10 @@ Provides-Extra: develop
 Requires-Dist: pytest==9.0.1; extra == "develop"
 Requires-Dist: ruff; extra == "develop"
 Requires-Dist: build==1.3.0; extra == "develop"
-Requires-Dist: twine==6.2.0; extra == "develop"
 Requires-Dist: pytest-cov==7.0.0; extra == "develop"
 Dynamic: license-file
 
-# Pi Hole Long Term Statistics v.0.2.4
+# Pi Hole Long Term Statistics v.0.2.6
 
 <div align="center">
 
@@ -74,11 +73,13 @@ See more [screenshots](https://github.com/davistdaniel/PiHoleLongTermStats/blob/
 > Using your actual Pi-hole FTL db file for querying is **not** recommended and it is advised to use a copy. Place the copy in the project root or specify its path using the `--db_path` argument or `PIHOLE_LT_STATS_DB_PATH` environment variable. In any case, PiHoleLongTermStats does not monitor for changes in the Pi-hole FTL db file even if you mount it.
 
 > [!TIP]
-> * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the live database. Use the reload button in the dashboard to refresh the stats.
+> * You can set up a cron job to periodically copy the FTL database to the `db_path` `PIHOLE_LT_STATS_DB_PATH` location, ensuring your stats are updated without touching the actual database. Use the reload button in the dashboard to refresh the stats.
 > * Set your timezone (e.g "Europe/Berlin") using `--timezone` or `PIHOLE_LT_STATS_TIMEZONE`.
 
 > [!IMPORTANT]
-> * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the dashboard is refreshed or the reload button is clicked.
+> * PiHoleLongTermStats reloads the Pi-hole FTL database and recalculates stats whenever the the reload button is clicked.
+> * Refreshing the page uing the browser's refresh button, will always serve cached dashboard and data.
+> * To update the dashboard with newer data from the database, you have to **manually** click the reload button (🔄) in the dashboard. Alternatively, you can restart the script or the docker container (using a cron job, for instance).
 > * If no date range is selected, it uses the default period set by `--days` or `PIHOLE_LT_STATS_DAYS`.
 > * Large date ranges may lead to increased memory usage.
 > * When multiple database files are provided, PiHoleLongTermStats concatenates them into a single dataframe and sorts the combined data by timestamp. Duplicate entries are **not** removed for calculating stats. Consolidating multiple databases can lead to increased memory usage.
@@ -104,7 +105,7 @@ If you have a copy of your `pihole-FTL.db` file, you can quickly run the dashboa
 
    ```bash
    # Example: Copy from the default Pi-hole location
-   sudo cp /etc/pihole/pihole-FTL.db . 
+   sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db" 
    # Ensure the user running the app has read permissions
    sudo chown $USER:$USER pihole-FTL.db
    ```
@@ -176,7 +177,7 @@ If installing using python, you can install from this git repo or as a package f
 
    ```bash
    # Example: Copy from the default Pi-hole location
-   sudo cp /etc/pihole/pihole-FTL.db . 
+   sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db"
    # Ensure the user running the app has read permissions
    sudo chown $USER:$USER pihole-FTL.db
    ```
@@ -231,7 +232,7 @@ If installing using python, you can install from this git repo or as a package f
 3. Make a copy/backup of your `pihole-FTL.db` (**Important!**) and place it in the PiHoleLongTermStats directory:
     ```bash
     # Example: Copy from the default Pi-hole location
-    sudo cp /etc/pihole/pihole-FTL.db . 
+    sudo sqlite3 /etc/pihole/pihole-FTL.db ".backup ./pihole-FTL.db"
     # Ensure the user running the app has read permissions
     sudo chown $USER:$USER pihole-FTL.db 
     ```
@@ -285,6 +286,7 @@ You can configure the application using command-line arguments or environment va
 ## 🧑‍💻 Contributing
 
 Any contribution, feature ideas or bug fixes are always welcome.
+In case of new features, opening an issue and discussion before implementation is recommended.
 This project uses uv for dependency management.
 
 ### Development workflow

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/piholelongtermstats.egg-info/requires.txt

@@ -7,5 +7,4 @@ psutil==7.2.2
 pytest==9.0.1
 ruff
 build==1.3.0
-twine==6.2.0
 pytest-cov==7.0.0

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "piholelongtermstats"
-version = "0.2.4"
+version = "0.2.6"
 dependencies = [
     "dash==4.1.0",
     "pandas==3.0.3",
@@ -32,7 +32,6 @@ develop = [
   "pytest==9.0.1",
   "ruff",
   "build==1.3.0",
-  "twine==6.2.0",
   "pytest-cov==7.0.0",
 ]
 
@@ -51,3 +50,8 @@ exclude = ["docs*", "tests*","screenshots*","build*","dist*"]
 
 [tool.setuptools.package-data]
 piholelongtermstats = ["assets/*"]
+
+[dependency-groups]
+dev = [
+    "jupyter>=1.1.1",
+]

{piholelongtermstats-0.2.4 → piholelongtermstats-0.2.6}/tests/test_plot.py

@@ -5,6 +5,8 @@ from piholelongtermstats.plot import (
     generate_plot_data,
     generate_queries_over_time,
     generate_client_activity_over_time,
+    generate_top_blocked_domains,
+    generate_top_allowed_domains,
 )
 from piholelongtermstats.process import prepare_hourly_aggregated_data
 
@@ -32,6 +34,8 @@ class TestGeneratePlotData:
             "top_clients_stacked",
             "blocked_df",
             "allowed_df",
+            "blocked_df_by_client",
+            "allowed_df_by_client",
             "reply_time_df",
             "client_list",
             "data_span_days",
@@ -81,6 +85,42 @@ class TestGeneratePlotData:
         assert len(blocked_df) <= n_domains
         assert len(allowed_df) <= n_domains
 
+        blocked_df_by_client = result["blocked_df_by_client"]
+        allowed_df_by_client = result["allowed_df_by_client"]
+
+        assert isinstance(blocked_df_by_client, pd.DataFrame)
+        assert isinstance(allowed_df_by_client, pd.DataFrame)
+        assert "client" in blocked_df_by_client.columns
+        assert "client" in allowed_df_by_client.columns
+
+    def test_generate_top_blocked_domains_function(self, plot_dataframe):
+        n_clients = 5
+        n_domains = 10
+        result = generate_plot_data(plot_dataframe, n_clients, n_domains)
+        callback_data = result
+
+        fig = generate_top_blocked_domains(callback_data, n_domains=n_domains)
+        assert isinstance(fig, go.Figure)
+
+        client = plot_dataframe["client"].iloc[0]
+        fig_client = generate_top_blocked_domains(callback_data, n_domains=n_domains, client=client)
+        assert isinstance(fig_client, go.Figure)
+        assert client in fig_client.layout.title.text
+
+    def test_generate_top_allowed_domains_function(self, plot_dataframe):
+        n_clients = 5
+        n_domains = 10
+        result = generate_plot_data(plot_dataframe, n_clients, n_domains)
+        callback_data = result
+
+        fig = generate_top_allowed_domains(callback_data, n_domains=n_domains)
+        assert isinstance(fig, go.Figure)
+
+        client = plot_dataframe["client"].iloc[0]
+        fig_client = generate_top_allowed_domains(callback_data, n_domains=n_domains, client=client)
+        assert isinstance(fig_client, go.Figure)
+        assert client in fig_client.layout.title.text
+
     def test_generate_plot_data_reply_time_df(self, plot_dataframe):
         """Test reply time dataframe."""
         n_clients = 5

piholelongtermstats-0.2.4/piholelongtermstats/__init__.py

@@ -1,3 +0,0 @@
-## Author :  Davis T. Daniel
-## PiHoleLongTermStats v.0.2.4
-## License :  MIT