notify-broadcast 0.0.3__tar.gz

notify_broadcast-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

notify_broadcast-0.0.3/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: notify-broadcast
+Version: 0.0.3
+Summary: Broadcast version of notify-send to allow root processes to send a notification to all users with an active DBUS session
+Author-email: Jason But <jbut@swin.edu.au>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jason-but/notify-broadcast
+Project-URL: Issues, https://github.com/jason-but/notify-broadcast/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorlog
+Requires-Dist: dasbus
+Requires-Dist: psutil
+Requires-Dist: pygobject
+Dynamic: license-file
+
+# notify-broadcast
+
+This program was developed because I run a number of **cron** jobs as root that I would like to be
+able to send notifications to the GUI User
+
+`notify-send` only functions if run by the same user running the graphical session.
+
+I created `notify-broadcast` to effectively tack the same parameters as `notify-send` but that
+could be executed by the `root` user.
+
+The application searches for all active DBUS Notification sessions, and sends the notification to
+all currently attached users.
+
+## Installation
+
+When complete, should be:
+
+```console
+pip install notify-broadcast
+```
+
+Seek information elsewhere about installing in a virtual environment
+
+The install should pull in all dependencies. At present these are:
+- colorlog: https://github.com/borntyping/python-colorlog/
+- dasbus: https://github.com/dasbus-project/dasbus
+- psutil: https://github.com/giampaolo/psutil
+- PyGObject: https://pygobject.gnome.org
+
+## Usage
+
+```console
+# notify-broadcast --help
+usage: notify-broadcast [--help] [-a APP_NAME] [-i ICON] [-t EXPIRE_TIME] [-h TYPE:NAME:VALUE] [-c TYPE] [-u {low,normal,critical}] [-A NAME=VALUE] [-r REPLACE_ID] [-p] [-e HINT] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+                        [--global-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+                        summary body
+
+Notify Broadcast Send a Broadcast DBUS notification to all users
+
+positional arguments:
+  summary               exam configuration file to be used for student collection - toml format
+  body                  exam solution file to be placed in collection directory
+
+options:
+  --help                show this help message and exit
+  -a APP_NAME, --app-name APP_NAME
+                        Specifies the app name for the notification (default: )
+  -i ICON, --icon ICON  Specifies an icon filename or stock icon to display. (default: dialog-information)
+  -t EXPIRE_TIME, --expire-time EXPIRE_TIME
+                        The duration, in milliseconds, for the notification to appear on screen. Value of 0 means no expiry, while -1 uses the server default expiry. (default: -1)
+  -h TYPE:NAME:VALUE, --hint TYPE:NAME:VALUE
+                        Notification hints to pass to server (e.g., int:urgency:2) (default: {})
+  -c TYPE, --category TYPE
+                        Specifies the notification category. (default: {})
+  -u {low,normal,critical}, --urgency {low,normal,critical}
+                        Specifies the urgency level (low, normal, critical). (default: {})
+  -A NAME=VALUE, --action NAME=VALUE
+                        Specifies the actions to display to the user. Implies --wait to wait for user input. May be set multiple times. The NAME of the action is output to stdout. If NAME is not specified, the numerical index of the
+                        option is used (starting with 1). (default: [])
+  -r REPLACE_ID, --replace-id REPLACE_ID
+                        The ID of the notification to replace. (default: 0)
+  -p, --print-id        Print the notification ID. (default: False)
+  -e HINT, --transient HINT
+                        Show a transient notification. Transient notifications by-pass the server's persistence capability, if any. And so it won't be preserved until the user acknowledges it. (default: {})
+  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Set the logging level for the core application. (default: None)
+  --global-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Set the global logging level (includes third-party libraries). (default: None)
+```
+
+**NOTE:** For more support on these parameters, see `notify-send` man pages
+
+## Examples
+
+Some examples of how to use `notify-broadcast` are listed below. These are by no means exhaustive:
+
+`notify-broadcast -a Daily-backup -t 0 -i dialog-information.png "Backup completed without error" ""`
+
+Display a notification that the backup has completed without error:
+ - Display an information icon
+ - A timeout of 0 signifies that the notification will display until the user clears it
+ - Message contains a summary, but no body
+
+`notify-broadcast -a Remote-rsync -t 6000 -i dialog-warning.png "Remote host not currently on the network" ""`
+
+Display a notification that the remote host is not available:
+ - Display a warning icon
+ - A timeout of 6000 signifies that the notification will display for six seconds before clearing
+ - Message contains a summary, but no body
+
+`notify-broadcast -a Daily-backup -t 0 -i dialog-error.png "Error running backup, please consult logs" ""`
+
+Display a notification that the backup has completed without error:
+ - Display an error icon
+ - A timeout of 0 signifies that the notification will display until the user clears it
+ - Message contains a summary, but no body
+
+`notify-broadcast -a "Disk Monitor" -h string:desktop-entry:org.kde.kinfocenter-i drive-harddisk "Disk" "SMART warning"`
+
+Display a notification that a disk has encountered a SMART error:
+ - Display an disk icon
+ - No timeout signifies that the notification will display for the system default duration
+
+## Comments
+
+I am aware of a number of potential shortcomings that may impact broader distribution, as well as
+some points about why things were coded this way, details listed below
+
+### Finding DBUS Path via environment variables instead of `/run/user/{uid}/bus`
+
+The code searches for the `DBUS_SESSION_BUS_ADDRESS` environment variable in a running program,
+while many online examples suggest searching `/run/user/{uid}/bus`
+
+My system (Gentoo) does not place the DBUS sockets in that location, so searching the environment
+variables allows this to work regardless of the location of the socket.
+
+### Program is hard-coded to KDE
+
+As per the previous point, to search the environment variables, it means finding a running 
+application that has the environment variables set. This means that we need to know the application
+name to search for.
+
+Hence, the program currently looks for running instances of `kwin_wayland` or `kwin_x11` depending
+on the current session type.
+
+This works for me as I use KDE, I don't like Gnome or other environments.
+
+However, I realise this means that this will not work everywhere. Some chat online suggests looking
+for `dbus-launch`, however the environment for this process does not appear to contain the
+`DBUS_SESSION_BUS_ADDRESS` environment variable.
+
+I would like to support alternate desktops, but I do not have the will to test and develop a
+solution. I am happy to take comments/suggestions on how to detect across multiple platforms.
+
+### Some of the Options are Useless for Broadcast application
+
+As a broadcast application, this really makes sense as a 1) send a message; and 2) do not wait for
+replies scenario
+
+1. `--print-id` makes no sense if sending multiple notifications
+2. `--replace-id` make no sense if we are just blasting information to everyone
+3. `--action` display buttons to the user and return values to the program. This is generally useless for this application
+
+### Running as non-root
+
+A non-root user will not be able to post notifications to other users in either case. The 
+application currently just prints warnings about being unable to access the environment and 
+does nothing else.
+
+It might be better to abort early if the user does not have permissions, but a system could
+allow multiple users the requisite permissions, so it is hard to manage this properly.

notify_broadcast-0.0.3/README.md

@@ -0,0 +1,151 @@
+# notify-broadcast
+
+This program was developed because I run a number of **cron** jobs as root that I would like to be
+able to send notifications to the GUI User
+
+`notify-send` only functions if run by the same user running the graphical session.
+
+I created `notify-broadcast` to effectively tack the same parameters as `notify-send` but that
+could be executed by the `root` user.
+
+The application searches for all active DBUS Notification sessions, and sends the notification to
+all currently attached users.
+
+## Installation
+
+When complete, should be:
+
+```console
+pip install notify-broadcast
+```
+
+Seek information elsewhere about installing in a virtual environment
+
+The install should pull in all dependencies. At present these are:
+- colorlog: https://github.com/borntyping/python-colorlog/
+- dasbus: https://github.com/dasbus-project/dasbus
+- psutil: https://github.com/giampaolo/psutil
+- PyGObject: https://pygobject.gnome.org
+
+## Usage
+
+```console
+# notify-broadcast --help
+usage: notify-broadcast [--help] [-a APP_NAME] [-i ICON] [-t EXPIRE_TIME] [-h TYPE:NAME:VALUE] [-c TYPE] [-u {low,normal,critical}] [-A NAME=VALUE] [-r REPLACE_ID] [-p] [-e HINT] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+                        [--global-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+                        summary body
+
+Notify Broadcast Send a Broadcast DBUS notification to all users
+
+positional arguments:
+  summary               exam configuration file to be used for student collection - toml format
+  body                  exam solution file to be placed in collection directory
+
+options:
+  --help                show this help message and exit
+  -a APP_NAME, --app-name APP_NAME
+                        Specifies the app name for the notification (default: )
+  -i ICON, --icon ICON  Specifies an icon filename or stock icon to display. (default: dialog-information)
+  -t EXPIRE_TIME, --expire-time EXPIRE_TIME
+                        The duration, in milliseconds, for the notification to appear on screen. Value of 0 means no expiry, while -1 uses the server default expiry. (default: -1)
+  -h TYPE:NAME:VALUE, --hint TYPE:NAME:VALUE
+                        Notification hints to pass to server (e.g., int:urgency:2) (default: {})
+  -c TYPE, --category TYPE
+                        Specifies the notification category. (default: {})
+  -u {low,normal,critical}, --urgency {low,normal,critical}
+                        Specifies the urgency level (low, normal, critical). (default: {})
+  -A NAME=VALUE, --action NAME=VALUE
+                        Specifies the actions to display to the user. Implies --wait to wait for user input. May be set multiple times. The NAME of the action is output to stdout. If NAME is not specified, the numerical index of the
+                        option is used (starting with 1). (default: [])
+  -r REPLACE_ID, --replace-id REPLACE_ID
+                        The ID of the notification to replace. (default: 0)
+  -p, --print-id        Print the notification ID. (default: False)
+  -e HINT, --transient HINT
+                        Show a transient notification. Transient notifications by-pass the server's persistence capability, if any. And so it won't be preserved until the user acknowledges it. (default: {})
+  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Set the logging level for the core application. (default: None)
+  --global-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Set the global logging level (includes third-party libraries). (default: None)
+```
+
+**NOTE:** For more support on these parameters, see `notify-send` man pages
+
+## Examples
+
+Some examples of how to use `notify-broadcast` are listed below. These are by no means exhaustive:
+
+`notify-broadcast -a Daily-backup -t 0 -i dialog-information.png "Backup completed without error" ""`
+
+Display a notification that the backup has completed without error:
+ - Display an information icon
+ - A timeout of 0 signifies that the notification will display until the user clears it
+ - Message contains a summary, but no body
+
+`notify-broadcast -a Remote-rsync -t 6000 -i dialog-warning.png "Remote host not currently on the network" ""`
+
+Display a notification that the remote host is not available:
+ - Display a warning icon
+ - A timeout of 6000 signifies that the notification will display for six seconds before clearing
+ - Message contains a summary, but no body
+
+`notify-broadcast -a Daily-backup -t 0 -i dialog-error.png "Error running backup, please consult logs" ""`
+
+Display a notification that the backup has completed without error:
+ - Display an error icon
+ - A timeout of 0 signifies that the notification will display until the user clears it
+ - Message contains a summary, but no body
+
+`notify-broadcast -a "Disk Monitor" -h string:desktop-entry:org.kde.kinfocenter-i drive-harddisk "Disk" "SMART warning"`
+
+Display a notification that a disk has encountered a SMART error:
+ - Display an disk icon
+ - No timeout signifies that the notification will display for the system default duration
+
+## Comments
+
+I am aware of a number of potential shortcomings that may impact broader distribution, as well as
+some points about why things were coded this way, details listed below
+
+### Finding DBUS Path via environment variables instead of `/run/user/{uid}/bus`
+
+The code searches for the `DBUS_SESSION_BUS_ADDRESS` environment variable in a running program,
+while many online examples suggest searching `/run/user/{uid}/bus`
+
+My system (Gentoo) does not place the DBUS sockets in that location, so searching the environment
+variables allows this to work regardless of the location of the socket.
+
+### Program is hard-coded to KDE
+
+As per the previous point, to search the environment variables, it means finding a running 
+application that has the environment variables set. This means that we need to know the application
+name to search for.
+
+Hence, the program currently looks for running instances of `kwin_wayland` or `kwin_x11` depending
+on the current session type.
+
+This works for me as I use KDE, I don't like Gnome or other environments.
+
+However, I realise this means that this will not work everywhere. Some chat online suggests looking
+for `dbus-launch`, however the environment for this process does not appear to contain the
+`DBUS_SESSION_BUS_ADDRESS` environment variable.
+
+I would like to support alternate desktops, but I do not have the will to test and develop a
+solution. I am happy to take comments/suggestions on how to detect across multiple platforms.
+
+### Some of the Options are Useless for Broadcast application
+
+As a broadcast application, this really makes sense as a 1) send a message; and 2) do not wait for
+replies scenario
+
+1. `--print-id` makes no sense if sending multiple notifications
+2. `--replace-id` make no sense if we are just blasting information to everyone
+3. `--action` display buttons to the user and return values to the program. This is generally useless for this application
+
+### Running as non-root
+
+A non-root user will not be able to post notifications to other users in either case. The 
+application currently just prints warnings about being unable to access the environment and 
+does nothing else.
+
+It might be better to abort early if the user does not have permissions, but a system could
+allow multiple users the requisite permissions, so it is hard to manage this properly.

notify_broadcast-0.0.3/notify_broadcast/__init__.py

@@ -0,0 +1,5 @@
+from .dbussessionmanager import DBUSSessionManager
+
+from .notifybroadcastargumentparser import NotifyBroadcastArgumentParser
+
+from .notify_broadcast import notify_broadcast

notify_broadcast-0.0.3/notify_broadcast/dbussessionmanager.py

@@ -0,0 +1,121 @@
+"""
+This module implements the DBUSSessionManager class which finds all user DBUS sessions and maps their NotificationProxy to allow broadcast of
+notifications to all users with a DBUS session
+"""
+# Import System Libraries
+import os
+import psutil
+import re
+import logging
+
+# Import dasbus library modules
+from dasbus.connection import SystemMessageBus, AddressedMessageBus
+from dasbus.client.proxy import InterfaceProxy
+
+
+class DBUSSessionManager:
+    class DBUSSessionNotFound(Exception):
+        """ This exception is raised when we cannot find the DBUS session for the nominated user and session type """
+        pass
+
+    def __init__(self, log_level: str):
+        """
+        Initialise class and internal variables:
+          - Store UID of current user so we can change EUID during running
+          - Populate __users mapping uid to a DBUS InterfaceProxy that we can use to notify that user
+
+        :param log_level: Level to set for the internal class logger
+        """
+        self.__log = logging.getLogger('DBUSSessionManager')
+        if log_level is not None:
+            self.__log.setLevel(log_level)
+        else:
+            self.__log.debug('using default log level')
+        self.__log.info(f'Constructing Class')
+
+        self.__app_uid = os.geteuid()
+        self.__log.debug(f'Storing UID of user running application: {self.__app_uid}')
+
+        self.__users: dict[int, InterfaceProxy] = {}
+        self.__find_users()
+        self.__log.debug(f'User DBUS sessions: {self.__users}')
+
+    def __get_notify_proxy(self, uid: int, name: str) -> InterfaceProxy:
+        """
+        Return a DBUS Notification Proxy for the given user, running the graphical session from the provided process name
+
+        :param uid: User ID for a given session
+        :param name: Name of the program to search for
+
+        :return: The DBUS Notification Proxy to send notifications to the user via the attached session
+        """
+        try:
+            # 1) Find the process ID for program "name" owned by self.__uid
+            self.__log.debug(f'Searching for process "{name}"')
+            manager_pid = [p.pid for p in psutil.process_iter(['name', 'pid', 'uids']) if p.info['name'] == name and p.info['uids'].real == uid][0]
+            self.__log.debug(f'Found Process ID: {manager_pid}')
+
+            # 2) Search the environment for manager_pid, and extract the DBUS session address
+            self.__log.debug('Reading Process environment')
+            with open(f'/proc/{manager_pid}/environ', 'rb') as f:
+                env_bytes = f.read()
+
+            # Regex pattern to locate DBUS addresses inside environment blocks
+            self.__log.debug('Searching for DBUS Session Bus Address')
+            dbus_pattern = re.compile(b"DBUS_SESSION_BUS_ADDRESS=(unix:path=[^\\x00]+)")
+            dbus_match = dbus_pattern.search(env_bytes)
+
+            if not dbus_match:
+                raise DBUSSessionManager.DBUSSessionNotFound(f'No DBUS Session Address found in environment for process ID ({manager_pid})')
+
+            dbus_path = dbus_match.group(1).decode('utf-8')
+            self.__log.debug(f'DBUS Session Path: {dbus_path}')
+
+            # 3) Create and return Notifications Proxy for the nominated path
+            self.__log.debug(f'Creating Notification Proxy')
+            return AddressedMessageBus(dbus_path).get_proxy("org.freedesktop.Notifications", "/org/freedesktop/Notifications")
+
+        except IndexError:
+            raise DBUSSessionManager.DBUSSessionNotFound(f'Unable to locate process "{name}"')
+
+        except (IOError, PermissionError):
+            raise DBUSSessionManager.DBUSSessionNotFound(f'Unable to access environment variables for process ID ({manager_pid}) - Need to run as root or user with appropriate permissions')
+
+    def __find_users(self):
+        """
+        Find all users with a login session, locate if they have a DBUS session attached to it, then populate __users with that information
+        """
+        self.__log.info('Finding DBUS sessions for all users')
+        bus = SystemMessageBus()
+        login_bus = bus.get_proxy("org.freedesktop.login1", "/org/freedesktop/login1")
+
+        for session_id, uid, username, seat, path in login_bus.ListSessions():
+            # Get session details for this login
+            session_proxy = bus.get_proxy("org.freedesktop.login1", path)
+            if session_proxy.Type in ['wayland', 'x11']:
+                try:
+                    self.__log.info(f'Login session {session_id}: User [{username}({uid})] on seat[{seat}] is a {session_proxy.Type} session')
+                    self.__users[uid] = self.__get_notify_proxy(uid, f'kwin_{session_proxy.Type}')
+                except DBUSSessionManager.DBUSSessionNotFound as e:
+                    self.__log.warning(e)
+            else:
+                self.__log.info(f'Non-graphical login session {session_id}: User [{username}({uid})]')
+
+    def broadcast_notification(self, notification: tuple, print_id: bool):
+        """
+        Broadcast a notification to all users using the DBUS Notification Proxies as listed in __users
+
+        :param notification: Tuple containing parameters to pass to the Notify() method of the Notification Proxy
+        :param print_id: Boolean indicating whether the message ID should be printed to screen
+        """
+        self.__log.info(f'Sending notification ({notification}) to all users')
+        for uid, notify_proxy in self.__users.items():
+            self.__log.debug(f'Changing UID to {uid} to send notification')
+            os.seteuid(uid)
+
+            self.__log.info(f'User({uid}): Sending Notification')
+            notify_id = notify_proxy.Notify(*notification)
+            if print_id: print(notify_id)
+
+            self.__log.debug(f'Reverting UID to {self.__app_uid}')
+            os.seteuid(self.__app_uid)

notify_broadcast-0.0.3/notify_broadcast/notify_broadcast.py

@@ -0,0 +1,28 @@
+"""
+This module implements the notify-broadcast application. The application is installed as a script which runs the notify_broadcast()
+function contained within this file
+"""
+# Import System Libraries
+import colorlog
+
+# Import Package Modules
+from notify_broadcast import NotifyBroadcastArgumentParser
+from notify_broadcast import DBUSSessionManager
+
+
+def notify_broadcast():
+    """
+    This is the main application which will be called directly when running the installed notify-broadcast application
+    """
+    # Create the command line argument parser and parse all arguments
+    parser = NotifyBroadcastArgumentParser()
+    parser.parse_args()
+
+    # Set the default logging format
+    colorlog.basicConfig(format='%(log_color)s[%(levelname)-8s] %(reset)s%(name)s.%(funcName)s() - %(log_color)s%(message)s%(reset)s',
+                         log_colors={'DEBUG': 'cyan', 'INFO': 'green', 'WARNING': 'yellow', 'ERROR': 'red', 'CRITICAL': 'red,bg_white'}
+                         )
+
+    # Create the DBUSSessionManager, then broadcast the notification to all users
+    dbus_manager = DBUSSessionManager(parser.log_level)
+    dbus_manager.broadcast_notification(parser.notification, parser.print_id)

notify_broadcast-0.0.3/notify_broadcast/notifybroadcastargumentparser.py

@@ -0,0 +1,321 @@
+"""
+This module implements the NotifyBroadcastArgumentParser class which provides the command-line argument parser for the notify-broadcast command
+"""
+# Import System Libraries
+import argparse
+import logging
+from gi.repository import GLib
+
+
+class NotifyBroadcastArgumentParser(argparse.ArgumentParser):
+    """
+    Extends ArgumentParser to provide parameter parsing for the notify-broadcast command.
+
+    Installs arguments similar to notify-send
+    """
+    class NotifyHints(argparse.Action):
+        """
+        Process one or more command line options in form TYPE:NAME:VALUE and appends a dictionary value mapping NAME -> VALUE cast to the
+        specified TYPE
+
+        NOTE: This class is designed to be used for validating a formatted parameter in the context of command-line argument parsing.
+        When an instance of this class is called with a string, it checks if the string conforms to the appropriate format specification.
+        If the provided string is in error, it raises an error suitable for argument parsing utilities.
+        """
+        def __init__(self, option_strings, dest, nargs=None, **kwargs):
+            """Initialise argument to empty dictionary"""
+            kwargs.setdefault('default', {})
+            super().__init__(option_strings, dest, **kwargs)
+
+        def __call__(self, parser, namespace, values, option_string=None):
+            """
+            Parse command line option as TYPE:NAME:VALUE and append to dictionary mapping name-->value(cast to type)
+
+            :param parser: ArgParse instance, used to send errors back to the parser.
+            :param namespace: Current parsed parameters.
+            :param values: Current option being parsed.
+            :param option_string: Actual option (e.g. --hint)
+            """
+            # Get the pre-existing parameter dictionary
+            current_values = getattr(namespace, self.dest)
+
+            # Split parameter to TYPE:NAME:VALUE tuple and add to dictionary
+            try:
+                parts = values.split(':', 2)
+                if len(parts) != 3: raise ValueError(f'Parameter should contain three values in format TYPE:NAME:VALUE, only {len(parts)} values provided')
+
+                raw_type, name, raw_value = parts
+
+                match raw_type.lower():
+                    case'int':
+                        variant_val = GLib.Variant('i', int(raw_value))
+                    case 'double':
+                        variant_val = GLib.Variant('d', float(raw_value))
+                    case 'boolean' | 'bool':
+                        variant_val = GLib.Variant('b', raw_value.lower() in ('true', '1', 'yes'))
+                    case 'byte':
+                        variant_val = GLib.Variant('y', int(raw_value))
+                    case _:  # Default to string
+                        variant_val = GLib.Variant('s', str(raw_value))
+
+                current_values[name] = variant_val
+
+            except ValueError as e:
+                parser.error(f'Invalid parameter "{option_string} {values}" is invalid: {e}')
+
+            # Save dictionary back to namespace
+            setattr(namespace, self.dest, current_values)
+
+    class NotifyUrgency(argparse.Action):
+        """
+        Process command line options as human-readable "urgency" values and map directly into hints directory as corresponding byte values
+        under the name "urgency"
+
+        NOTE: String values should be checked by argparse, so no errors should be raised here, merely convert string->byte and append to
+        dictionary
+        """
+        def __init__(self, option_strings, dest, **kwargs):
+            """Initialise argument to empty dictionary"""
+            kwargs.setdefault('default', {})
+            super().__init__(option_strings, dest, **kwargs)
+
+        def __call__(self, parser, namespace, values, option_string=None):
+            """
+            Parse command line option as low, normal, or critical, and append to dictionary with corresponding byte value under key name 'urgency'
+
+            :param parser: ArgParse instance, used to send errors back to the parser.
+            :param namespace: Current parsed parameters.
+            :param values: Current option being parsed.
+            :param option_string: Actual option (e.g. --urgency)
+            """
+            # Get the pre-existing parameter dictionary
+            current_values = getattr(namespace, self.dest)
+
+            urgency_mapping = {'low': 0, 'normal': 1, 'critical': 2}
+
+            # Inject the key directly into the dictionary as a D-Bus byte variant
+            current_values['urgency'] = GLib.Variant('y', urgency_mapping[values])
+
+            # Save dictionary back to namespace
+            setattr(namespace, self.dest, current_values)
+
+    class NotifyCategory(argparse.Action):
+        """
+        Process command line options as string "category" value and map directly into hints directory as corresponding string under the
+        name "category"
+
+        NOTE: String value provided already, so no errors should be raised here, merely append string to dictionary
+        """
+        def __init__(self, option_strings, dest, **kwargs):
+            """Initialise argument to empty dictionary"""
+            kwargs.setdefault('default', {})
+            super().__init__(option_strings, dest, **kwargs)
+
+        def __call__(self, parser, namespace, values, option_string=None):
+            """
+            Parse command line option as string, and append to dictionary with corresponding string value under key name 'category'
+
+            :param parser: ArgParse instance, used to send errors back to the parser.
+            :param namespace: Current parsed parameters.
+            :param values: Current option being parsed.
+            :param option_string: Actual option (e.g. --option)
+            """
+            # Get the pre-existing parameter dictionary
+            current_values = getattr(namespace, self.dest)
+
+            # Inject the key directly into the dictionary as a D-Bus string variant
+            current_values['category'] = GLib.Variant('s', str(values))
+
+            # Save dictionary back to namespace
+            setattr(namespace, self.dest, current_values)
+
+    class NotifyTransient(argparse.Action):
+        """
+        Process command line flag to activate transient feature. Map directory into hints dictionary as "transient"->True
+
+        NOTE: Simple parameter flag, so no errors should be raised here, merely append True to dictionary
+        """
+        def __init__(self, option_strings, dest, **kwargs):
+            """Initialise argument to empty dictionary"""
+            kwargs.setdefault('default', {})
+            super().__init__(option_strings, dest, **kwargs)
+
+        def __call__(self, parser, namespace, values, option_string=None):
+            """
+            Transient should be a flag on the command line, so this action is called to set flag to True. Append True value to dictionary
+            under key name 'transient'
+
+            :param parser: ArgParse instance, used to send errors back to the parser.
+            :param namespace: Current parsed parameters.
+            :param values: Current option being parsed.
+            :param option_string: Actual option (e.g. --option)
+            """
+            # Get the pre-existing parameter dictionary
+            current_values = getattr(namespace, self.dest)
+
+            # Inject the key directly into the dictionary as a D-Bus byte variant
+            current_values['transient'] = GLib.Variant('b', True)
+
+            # Save dictionary back to namespace
+            setattr(namespace, self.dest, current_values)
+
+    class NotifyAction(argparse.Action):
+        """
+        Process one or more command line options in form KEY=LABEL or KEY:LABEL and append them to a flat "actions" list
+
+        NOTE: This class is designed to be used for validating a formatted parameter in the context of command-line argument parsing.
+        When an instance of this class is called with a string, it checks if the string conforms to the appropriate format specification.
+        If the provided string is in error, it raises an error suitable for argument parsing utilities.
+        """
+        def __init__(self, option_strings, dest, nargs=None, **kwargs):
+            """Initialise argument to empty list"""
+            kwargs.setdefault('default', [])
+            super().__init__(option_strings, dest, **kwargs)
+
+        def __call__(self, parser, namespace, values, option_string=None):
+            """
+            Parse command line option as KEY=LABEL or KEY:LABEL and extend the existing list with two new entries [KEY, LABEL]
+
+            :param parser: ArgParse instance, used to send errors back to the parser.
+            :param namespace: Current parsed parameters.
+            :param values: Current option being parsed.
+            :param option_string: Actual option (e.g. --hint)
+            """
+            # Get the pre-existing parameter list
+            actions_list = getattr(namespace, self.dest)
+
+            # Allow splitting by either ':' or ',' to match common notify-send clones
+            delimiter = '=' if '=' in values else ':'
+
+            try:
+                parts = values.split(delimiter, 1)
+                if len(parts) != 2: raise ValueError(f'Must be in "KEY=LABEL" or "KEY:LABEL" format')
+
+                key, label = parts[0].strip(), parts[1].strip()
+                if not key: raise ValueError('Key cannot be an empty string')
+                if not label: raise ValueError('Label cannot be an empty string')
+
+                # D-Bus expects a flat list: [key1, label1, key2, label2]
+                actions_list.extend([key, label])
+
+            except Exception as e:
+                parser.error(f'Invalid parameter "{option_string} {values}" is invalid: {e}')
+
+            # Save dictionary back to namespace
+            setattr(namespace, self.dest, actions_list)
+
+    class SetGlobalLogLevel(argparse.Action):
+        """
+        Process the global-log-level parameter and set the default system log level as an action
+
+        NOTE: This class is designed to be used for validating a formatted parameter in the context of command-line argument parsing.
+        When an instance of this class is called with a string, it checks if the string conforms to the appropriate format specification.
+        If the provided string is in error, it raises an error suitable for argument parsing utilities.
+        """
+        def __call__(self, parser, namespace, values, option_string=None):
+            """
+            Parse command line option as DEBUG, INFO, WARNING, ERROR, or CRITICAL, then set the logging log-level to match
+
+            :param parser: ArgParse instance, used to send errors back to the parser.
+            :param namespace: Current parsed parameters.
+            :param values: Current option being parsed.
+            :param option_string: Actual option (e.g. --urgency)
+            """
+            logging.basicConfig(level=values)
+
+            # Save the value to the namespace for standard argparse behavior
+            setattr(namespace, self.dest, values)
+
+    # NotifyBroadcastArgumentParser member methods begin here
+    def __init__(self, *args, **kwargs):
+        """
+        Overloaded Constructor
+
+        Set default description and argparse parameters before calling superclass constructor
+
+        Then call add_arguments() to add the required command-line parameters
+        """
+        # Default options
+        kwargs.setdefault('description', 'Notify Broadcast\n\nSend a Broadcast DBUS notification to all users')
+        kwargs.setdefault('formatter_class', argparse.ArgumentDefaultsHelpFormatter)
+        kwargs.setdefault('allow_abbrev', False)
+        kwargs.setdefault('conflict_handler', 'resolve')
+
+        # Initialise the parent class
+        super().__init__(*args, **kwargs)
+
+        # Add parameter options
+        self.__add_arguments()
+
+        # Create variable to store generated notification from parsed arguments
+        self.__notification = None
+        self.__print_id = None
+        self.__log_level = None
+
+    def __add_arguments(self):
+        """ Add command line arguments to the argument parser """
+        self.add_argument('-a', '--app-name', type=str, default='', help='Specifies the app name for the notification')
+        self.add_argument('-i', '--icon', type=str, default='dialog-information', help='Specifies an icon filename or stock icon to display.')
+        self.add_argument('-t', '--expire-time', type=int, default=-1, help='The duration, in milliseconds, for the notification to appear on screen. Value of 0 means no expiry, while -1 uses the server default expiry.')
+        self.add_argument('-h', '--hint', action=NotifyBroadcastArgumentParser.NotifyHints, metavar='TYPE:NAME:VALUE', help='Notification hints to pass to server (e.g., int:urgency:2)')
+        self.add_argument('-c', '--category', action=NotifyBroadcastArgumentParser.NotifyCategory, metavar='TYPE', dest='hint', help='Specifies the notification category.')
+        self.add_argument('-u', '--urgency', action=NotifyBroadcastArgumentParser.NotifyUrgency, choices=['low', 'normal', 'critical'], dest='hint', help='Specifies the urgency level (low, normal, critical).')
+
+        self.add_argument('-A', '--action', action=NotifyBroadcastArgumentParser.NotifyAction, metavar='NAME=VALUE', help='Specifies the actions to display to the user. Implies --wait to wait for user input. May be set multiple times. The NAME of the action is output to stdout. If NAME is not specified, the numerical index of the option is used (starting with 1).')
+
+        self.add_argument('-r', '--replace-id', type=int, default=0, help='The ID of the notification to replace.')
+        self.add_argument('-p', '--print-id', action='store_true', help='Print the notification ID.')
+
+        self.add_argument('-e', '--transient', action=NotifyBroadcastArgumentParser.NotifyTransient, dest='hint', help='Show a transient notification. Transient notifications by-pass the server\'s persistence capability, if any. And so it won\'t be preserved until the user acknowledges it.')
+
+        self.add_argument('summary', type=str, help='exam configuration file to be used for student collection - toml format')
+        self.add_argument('body', type=str, help='exam solution file to be placed in collection directory')
+
+        self.add_argument("--log-level", choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], help="Set the logging level for the core application.")
+
+        self.add_argument("--global-log-level", action=NotifyBroadcastArgumentParser.SetGlobalLogLevel, choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], help="Set the global logging level (includes third-party libraries).")
+
+    def parse_args(self, args=None, namespace=None):
+        """
+        Overload parse_args method. Constructs the notification details (stored in __notification) from the parsed command line arguments.
+          - Call the base class method to parse the arguments and store in temporary variable
+          - Extract parameters into a tuple (ready to pass to Notify()) and store in __notification
+          - Extract other variables to make directly accessible via properties
+
+        :return: Return the parsed arguments Namespace as required by parse_args()
+        """
+        # Call base class method to parse arguments and store in internal variable
+        parsed = super().parse_args(args=args, namespace=namespace)
+
+        self.__notification = (parsed.app_name, parsed.replace_id, parsed.icon, parsed.summary, parsed.body, parsed.action, parsed.hint, parsed.expire_time)
+        self.__print_id = parsed.print_id
+        self.__log_level = parsed.log_level
+
+        return parsed
+
+    @property
+    def notification(self) -> tuple:
+        """
+        Retrieves the notification constructed from the command line arguments as a class property.
+
+        :return: The value stored in internal variable __notification
+        """
+        return self.__notification
+
+    @property
+    def print_id(self) -> bool:
+        """
+        Retrieves the print_id from the command line arguments as a class property.
+
+        :return: The value stored in internal variable __print_id
+        """
+        return self.__print_id
+
+    @property
+    def log_level(self) -> str:
+        """
+        Retrieves the log_level from the command line arguments as a class property.
+
+        :return: The value stored in internal variable __log_level
+        """
+        return self.__log_level

notify_broadcast-0.0.3/notify_broadcast.egg-info/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: notify-broadcast
+Version: 0.0.3
+Summary: Broadcast version of notify-send to allow root processes to send a notification to all users with an active DBUS session
+Author-email: Jason But <jbut@swin.edu.au>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jason-but/notify-broadcast
+Project-URL: Issues, https://github.com/jason-but/notify-broadcast/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorlog
+Requires-Dist: dasbus
+Requires-Dist: psutil
+Requires-Dist: pygobject
+Dynamic: license-file
+
+# notify-broadcast
+
+This program was developed because I run a number of **cron** jobs as root that I would like to be
+able to send notifications to the GUI User
+
+`notify-send` only functions if run by the same user running the graphical session.
+
+I created `notify-broadcast` to effectively tack the same parameters as `notify-send` but that
+could be executed by the `root` user.
+
+The application searches for all active DBUS Notification sessions, and sends the notification to
+all currently attached users.
+
+## Installation
+
+When complete, should be:
+
+```console
+pip install notify-broadcast
+```
+
+Seek information elsewhere about installing in a virtual environment
+
+The install should pull in all dependencies. At present these are:
+- colorlog: https://github.com/borntyping/python-colorlog/
+- dasbus: https://github.com/dasbus-project/dasbus
+- psutil: https://github.com/giampaolo/psutil
+- PyGObject: https://pygobject.gnome.org
+
+## Usage
+
+```console
+# notify-broadcast --help
+usage: notify-broadcast [--help] [-a APP_NAME] [-i ICON] [-t EXPIRE_TIME] [-h TYPE:NAME:VALUE] [-c TYPE] [-u {low,normal,critical}] [-A NAME=VALUE] [-r REPLACE_ID] [-p] [-e HINT] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+                        [--global-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+                        summary body
+
+Notify Broadcast Send a Broadcast DBUS notification to all users
+
+positional arguments:
+  summary               exam configuration file to be used for student collection - toml format
+  body                  exam solution file to be placed in collection directory
+
+options:
+  --help                show this help message and exit
+  -a APP_NAME, --app-name APP_NAME
+                        Specifies the app name for the notification (default: )
+  -i ICON, --icon ICON  Specifies an icon filename or stock icon to display. (default: dialog-information)
+  -t EXPIRE_TIME, --expire-time EXPIRE_TIME
+                        The duration, in milliseconds, for the notification to appear on screen. Value of 0 means no expiry, while -1 uses the server default expiry. (default: -1)
+  -h TYPE:NAME:VALUE, --hint TYPE:NAME:VALUE
+                        Notification hints to pass to server (e.g., int:urgency:2) (default: {})
+  -c TYPE, --category TYPE
+                        Specifies the notification category. (default: {})
+  -u {low,normal,critical}, --urgency {low,normal,critical}
+                        Specifies the urgency level (low, normal, critical). (default: {})
+  -A NAME=VALUE, --action NAME=VALUE
+                        Specifies the actions to display to the user. Implies --wait to wait for user input. May be set multiple times. The NAME of the action is output to stdout. If NAME is not specified, the numerical index of the
+                        option is used (starting with 1). (default: [])
+  -r REPLACE_ID, --replace-id REPLACE_ID
+                        The ID of the notification to replace. (default: 0)
+  -p, --print-id        Print the notification ID. (default: False)
+  -e HINT, --transient HINT
+                        Show a transient notification. Transient notifications by-pass the server's persistence capability, if any. And so it won't be preserved until the user acknowledges it. (default: {})
+  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Set the logging level for the core application. (default: None)
+  --global-log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Set the global logging level (includes third-party libraries). (default: None)
+```
+
+**NOTE:** For more support on these parameters, see `notify-send` man pages
+
+## Examples
+
+Some examples of how to use `notify-broadcast` are listed below. These are by no means exhaustive:
+
+`notify-broadcast -a Daily-backup -t 0 -i dialog-information.png "Backup completed without error" ""`
+
+Display a notification that the backup has completed without error:
+ - Display an information icon
+ - A timeout of 0 signifies that the notification will display until the user clears it
+ - Message contains a summary, but no body
+
+`notify-broadcast -a Remote-rsync -t 6000 -i dialog-warning.png "Remote host not currently on the network" ""`
+
+Display a notification that the remote host is not available:
+ - Display a warning icon
+ - A timeout of 6000 signifies that the notification will display for six seconds before clearing
+ - Message contains a summary, but no body
+
+`notify-broadcast -a Daily-backup -t 0 -i dialog-error.png "Error running backup, please consult logs" ""`
+
+Display a notification that the backup has completed without error:
+ - Display an error icon
+ - A timeout of 0 signifies that the notification will display until the user clears it
+ - Message contains a summary, but no body
+
+`notify-broadcast -a "Disk Monitor" -h string:desktop-entry:org.kde.kinfocenter-i drive-harddisk "Disk" "SMART warning"`
+
+Display a notification that a disk has encountered a SMART error:
+ - Display an disk icon
+ - No timeout signifies that the notification will display for the system default duration
+
+## Comments
+
+I am aware of a number of potential shortcomings that may impact broader distribution, as well as
+some points about why things were coded this way, details listed below
+
+### Finding DBUS Path via environment variables instead of `/run/user/{uid}/bus`
+
+The code searches for the `DBUS_SESSION_BUS_ADDRESS` environment variable in a running program,
+while many online examples suggest searching `/run/user/{uid}/bus`
+
+My system (Gentoo) does not place the DBUS sockets in that location, so searching the environment
+variables allows this to work regardless of the location of the socket.
+
+### Program is hard-coded to KDE
+
+As per the previous point, to search the environment variables, it means finding a running 
+application that has the environment variables set. This means that we need to know the application
+name to search for.
+
+Hence, the program currently looks for running instances of `kwin_wayland` or `kwin_x11` depending
+on the current session type.
+
+This works for me as I use KDE, I don't like Gnome or other environments.
+
+However, I realise this means that this will not work everywhere. Some chat online suggests looking
+for `dbus-launch`, however the environment for this process does not appear to contain the
+`DBUS_SESSION_BUS_ADDRESS` environment variable.
+
+I would like to support alternate desktops, but I do not have the will to test and develop a
+solution. I am happy to take comments/suggestions on how to detect across multiple platforms.
+
+### Some of the Options are Useless for Broadcast application
+
+As a broadcast application, this really makes sense as a 1) send a message; and 2) do not wait for
+replies scenario
+
+1. `--print-id` makes no sense if sending multiple notifications
+2. `--replace-id` make no sense if we are just blasting information to everyone
+3. `--action` display buttons to the user and return values to the program. This is generally useless for this application
+
+### Running as non-root
+
+A non-root user will not be able to post notifications to other users in either case. The 
+application currently just prints warnings about being unable to access the environment and 
+does nothing else.
+
+It might be better to abort early if the user does not have permissions, but a system could
+allow multiple users the requisite permissions, so it is hard to manage this properly.

notify_broadcast-0.0.3/notify_broadcast.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+notify_broadcast/__init__.py
+notify_broadcast/dbussessionmanager.py
+notify_broadcast/notify_broadcast.py
+notify_broadcast/notifybroadcastargumentparser.py
+notify_broadcast.egg-info/PKG-INFO
+notify_broadcast.egg-info/SOURCES.txt
+notify_broadcast.egg-info/dependency_links.txt
+notify_broadcast.egg-info/entry_points.txt
+notify_broadcast.egg-info/requires.txt
+notify_broadcast.egg-info/top_level.txt

notify_broadcast-0.0.3/notify_broadcast.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

notify_broadcast-0.0.3/notify_broadcast.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+notify-broadcast = notify_broadcast.notify_broadcast:notify_broadcast

notify_broadcast-0.0.3/notify_broadcast.egg-info/requires.txt

@@ -0,0 +1,4 @@
+colorlog
+dasbus
+psutil
+pygobject

notify_broadcast-0.0.3/notify_broadcast.egg-info/top_level.txt

@@ -0,0 +1 @@
+notify_broadcast

notify_broadcast-0.0.3/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "notify-broadcast"
+version = "0.0.3"
+authors = [
+  { name="Jason But", email="jbut@swin.edu.au" },
+]
+description = "Broadcast version of notify-send to allow root processes to send a notification to all users with an active DBUS session"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = ["colorlog", "dasbus", "psutil", "pygobject"]
+
+[project.scripts]
+notify-broadcast = "notify_broadcast.notify_broadcast:notify_broadcast"
+
+[project.urls]
+Homepage = "https://github.com/jason-but/notify-broadcast"
+Issues = "https://github.com/jason-but/notify-broadcast/issues"

notify_broadcast-0.0.3/setup.cfg

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