Provide easy add access to apprise.Apprise (#9)

* Easy "add" method

* Improve documentation

* reformat

Author: svaningelgem

README.md

@@ -7,7 +7,7 @@ Logprise is a Python package that seamlessly integrates [loguru](https://github.
 - Unified logging interface that captures both standard logging and loguru logs
 - Automatic notification delivery based on configurable log levels
 - Batched notifications to prevent notification spam
-- Flexible configuration through apprise's extensive notification service support
+- Flexible configuration through apprises extensive notification service support
 - Periodic flushing of log messages at configurable intervals
 - Automatic capture of uncaught exceptions
 - Easy integration with existing Python applications
@@ -44,10 +44,17 @@ logger.error("This will trigger a notification")  # Default is ERROR level
 
 ### Notification Services
 
-Logprise uses Apprise for notifications, which supports a wide range of notification services. Create an `.apprise` file in one of the default configuration paths:
+Logprise uses Apprise for notifications, which supports a wide range of notification services. You can configure these in two ways:
 
-- `~/.apprise`
-- `~/.config/apprise`
+#### 1. Configuration File
+
+Create an `.apprise` file in one of the default configuration paths:
+
+- `~/.apprise` \[or `%APPDATA%/Apprise/apprise`]
+- `~/.config/apprise` \[or `%LOCALAPPDATA%/Apprise/apprise`]
+- '/etc/apprise' \[or `%ALLUSERSPROFILE%/Apprise/apprise`]
+
+*For more possible configuration file locations, please check: `DEFAULT_CONFIG_PATHS` in [apprises source code](https://github.com/caronc/apprise/blob/master/apprise/cli.py).*
 
 Example configuration:
 
@@ -57,6 +64,23 @@ tgram://bot_token/chat_id
 slack://tokenA/tokenB/tokenC/#channel
 ```
 
+#### 2. Programmatically Add Services
+
+You can easily add more notification services programmatically:
+
+```python
+from logprise import appriser
+
+# Add a single URL
+appriser.add("mailto://user:pass@gmail.com")
+
+# Add multiple URLs
+appriser.add(["tgram://bot_token/chat_id", "slack://tokenA/tokenB/tokenC/#channel"])
+
+# Add URLs with tags
+appriser.add("discord://webhook_id/webhook_token", tag=["critical"])
+```
+
 See [Apprise's configuration guide](https://github.com/caronc/apprise/wiki/config#cli) for the full list of supported services and their configuration.
 
 ### Notification Levels

logprise/__init__.py

@@ -18,7 +18,9 @@
 
 if TYPE_CHECKING:
     import types
-    from collections.abc import Callable
+    from collections.abc import Callable, Iterable
+
+    from apprise import AppriseAsset, AppriseConfig, ConfigBase, NotifyBase
 
 __all__ = ["appriser", "logger"]
 
@@ -153,6 +155,25 @@ def _start_periodic_flush(self) -> None:
         self._flush_thread = threading.Thread(target=self._periodic_flush, daemon=True, name="logprise-flush")
         self._flush_thread.start()
 
+    def add(
+        self,
+        servers: str | dict | Iterable | ConfigBase | NotifyBase | AppriseConfig,
+        asset: AppriseAsset = None,
+        tag: list[str] | None = None,
+    ) -> bool:
+        """
+        Adds one or more server URLs into our list.
+
+        This is a direct wrapper around the `apprise.Apprise.add()` method.
+        For detailed documentation, see:
+        https://github.com/caronc/apprise/wiki/Development_API#add-add-a-new-notification-service-by-urls
+
+        Returns:
+            True if the server(s) were added successfully, False otherwise.
+        """
+
+        return self.apprise_obj.add(servers=servers, asset=asset, tag=tag)
+
     def stop_periodic_flush(self) -> None:
         """Stop the periodic flush thread."""
         if self._flush_thread and self._flush_thread.is_alive():

tests/test_adding_add_method.py

@@ -0,0 +1,34 @@
+from logprise import Appriser
+
+
+def test_add_method(mocker):
+    """Test that add method correctly passes through to apprise_obj.add"""
+    appriser = Appriser()
+
+    # Create a mock for the underlying apprise_obj.add method
+    mock_add = mocker.patch.object(appriser.apprise_obj, "add", return_value=True)
+
+    # Test with a simple string URL
+    test_url = "mailto://user:pass@example.com"
+    assert appriser.add(test_url) is True
+
+    # Verify add was called with correct parameters
+    mock_add.assert_called_once_with(servers=test_url, asset=None, tag=None)
+
+    # Reset mock for next test
+    mock_add.reset_mock()
+
+    # Test with a dictionary
+    test_dict = {"urls": ["mailto://user:pass@example.com"]}
+    test_tag = ["important"]
+    assert appriser.add(test_dict, tag=test_tag) is True
+
+    # Verify add was called with correct parameters
+    mock_add.assert_called_once_with(servers=test_dict, asset=None, tag=test_tag)
+
+    # Test return value pass-through (False case)
+    mock_add.return_value = False
+    mock_add.reset_mock()
+
+    assert appriser.add("invalid://url") is False
+    mock_add.assert_called_once()