python-ntfy 0.8.0__tar.gz → 0.9.0__tar.gz

{python_ntfy-0.8.0 → python_ntfy-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ntfy
-Version: 0.8.0
+Version: 0.9.0
 Summary: An ntfy library aiming for feature completeness
 Keywords: ntfy,notifications,push,http,api
 Author: Matthew Cane
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 # A Python Library For ntfy
 
 ![GitHub Release](https://img.shields.io/github/v/release/MatthewCane/python-ntfy?display_name=release&label=latest%20release&link=https%3A%2F%2Fgithub.com%2FMatthewCane%2Fpython-ntfy%2Freleases%2Flatest)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/python-ntfy?logo=pypi&link=http%3A%2F%2Fpypi.org%2Fproject%2Fpython-ntfy%2F)
+[![PyPI Downloads](https://static.pepy.tech/badge/python-ntfy/month)](https://pepy.tech/projects/python-ntfy)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MatthewCane/python-ntfy/publish.yml?logo=githubactions&link=https%3A%2F%2Fgithub.com%2FMatthewCane%2Fpython-ntfy%2Factions%2Fworkflows%2Fpublish.yml)
 
 An easy-to-use python library for the [ntfy notification service](https://ntfy.sh/). Aiming for full feature support and a super easy to use interface.

{python_ntfy-0.8.0 → python_ntfy-0.9.0}/README.md

@@ -1,7 +1,7 @@
 # A Python Library For ntfy
 
 ![GitHub Release](https://img.shields.io/github/v/release/MatthewCane/python-ntfy?display_name=release&label=latest%20release&link=https%3A%2F%2Fgithub.com%2FMatthewCane%2Fpython-ntfy%2Freleases%2Flatest)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/python-ntfy?logo=pypi&link=http%3A%2F%2Fpypi.org%2Fproject%2Fpython-ntfy%2F)
+[![PyPI Downloads](https://static.pepy.tech/badge/python-ntfy/month)](https://pepy.tech/projects/python-ntfy)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MatthewCane/python-ntfy/publish.yml?logo=githubactions&link=https%3A%2F%2Fgithub.com%2FMatthewCane%2Fpython-ntfy%2Factions%2Fworkflows%2Fpublish.yml)
 
 An easy-to-use python library for the [ntfy notification service](https://ntfy.sh/). Aiming for full feature support and a super easy to use interface.

{python_ntfy-0.8.0 → python_ntfy-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-ntfy"
-version = "0.8.0"
+version = "0.9.0"
 description = "An ntfy library aiming for feature completeness"
 readme = "README.md"
 license = "MIT"
@@ -74,6 +74,9 @@ dev = [
 [tool.ruff]
 target-version = "py312"
 
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
 [tool.ruff.lint]
 select = [
     "E",    # PycodeStyle errors
@@ -125,3 +128,23 @@ addopts = [
     "--cov-fail-under=95",
     "--cov-report=term-missing",
 ]
+
+[tool.mypy]
+python_version = "3.12"
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+no_implicit_optional = true
+strict_equality = true
+pretty = true
+# Default expectations for the codebase; public modules may override to be stricter.
+disallow_incomplete_defs = false
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = [
+  "python_ntfy.client",
+  "python_ntfy.__init__",
+]
+disallow_incomplete_defs = true
+disallow_untyped_defs = true

python_ntfy-0.9.0/python_ntfy/__init__.py

@@ -0,0 +1,17 @@
+from ._exceptions import MessageSendError as MessageSendError
+from ._send_functions import (
+    BroadcastAction as BroadcastAction,
+    HttpAction as HttpAction,
+    MessagePriority as MessagePriority,
+    ViewAction as ViewAction,
+)
+from .client import NtfyClient as NtfyClient
+
+__all__ = [
+    "BroadcastAction",
+    "HttpAction",
+    "MessagePriority",
+    "MessageSendError",
+    "NtfyClient",
+    "ViewAction",
+]

python_ntfy-0.9.0/python_ntfy/_ntfy.py

@@ -0,0 +1,19 @@
+"""Compatibility shim for historical import path.
+
+Prefer importing from `python_ntfy` package root:
+
+    from python_ntfy import NtfyClient
+
+This module re-exports `NtfyClient` to maintain backward compatibility with
+older references like `python_ntfy._ntfy.NtfyClient`.
+"""
+
+from warnings import warn
+
+from .client import NtfyClient as NtfyClient
+
+warn(
+    "`python_ntfy._ntfy` is deprecated and will be removed in a future version. Please import from `python_ntfy` instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)

python_ntfy-0.9.0/python_ntfy/client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from pathlib import Path
+
+from ._get_functions import get_cached_messages as _get_cached_messages
+from ._send_functions import (
+    BroadcastAction as _BroadcastAction,
+    HttpAction as _HttpAction,
+    MessagePriority as _MessagePriority,
+    ViewAction as _ViewAction,
+    send as _send_message,
+    send_file as _send_file,
+)
+
+
+class NtfyClient:
+    """A client for interacting with the ntfy notification service."""
+
+    # Backwards-compatible attribute exposure (discouraged for new code):
+    BroadcastAction = _BroadcastAction
+    HttpAction = _HttpAction
+    MessagePriority = _MessagePriority
+    ViewAction = _ViewAction
+
+    def __init__(
+        self,
+        topic: str,
+        server: str = "https://ntfy.sh",
+        auth: tuple[str, str] | str | None = None,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            topic: The topic to use for this client.
+            server: The server base URL (must include protocol, e.g., https://).
+            auth: Credentials for this client. Takes precedence over environment
+                variables. May be a tuple ``(user, password)`` for Basic auth
+                or a token string for Bearer auth.
+        """
+        self._server = os.environ.get("NTFY_SERVER") or server
+        self._topic = topic
+        self.__set_url(self._server, topic)
+        self._auth: tuple[str, str] | None = self._resolve_auth(auth)
+
+    def _resolve_auth(
+        self, auth: tuple[str, str] | str | None
+    ) -> tuple[str, str] | None:
+        """Resolve authentication credentials using args or environment variables."""
+        # Explicitly provided credentials take precedence (including empty string)
+        if auth is not None:
+            if isinstance(auth, tuple):
+                return auth
+            if isinstance(auth, str):
+                return ("", auth)
+
+        # Fallback to environment variables
+        user = os.environ.get("NTFY_USER")
+        password = os.environ.get("NTFY_PASSWORD")
+        token = os.environ.get("NTFY_TOKEN")
+
+        if user and password:
+            return (user, password)
+        if token:
+            return ("", token)
+
+        return None
+
+    def __set_url(self, server: str, topic: str) -> None:
+        self.url = server.strip("/") + "/" + topic
+
+    def set_topic(self, topic: str) -> None:
+        """Set a new topic for this client."""
+        self._topic = topic
+        self.__set_url(self._server, self._topic)
+
+    def get_topic(self) -> str:
+        """Get the current topic."""
+        return self._topic
+
+    # Public API methods delegate to internal helpers for implementation
+
+    def send(
+        self,
+        message: str,
+        title: str | None = None,
+        priority: _MessagePriority = _MessagePriority.DEFAULT,
+        tags: list[str] | None = None,
+        actions: list[_ViewAction | _BroadcastAction | _HttpAction] | None = None,
+        schedule: datetime | None = None,
+        format_as_markdown: bool = False,
+        timeout_seconds: int = 5,
+        email: str | None = None,
+    ) -> dict:
+        """Send a text-based message to the server."""
+        return _send_message(
+            self,
+            message=message,
+            title=title,
+            priority=priority,
+            tags=tags,
+            actions=actions,
+            schedule=schedule,
+            format_as_markdown=format_as_markdown,
+            timeout_seconds=timeout_seconds,
+            email=email,
+        )
+
+    def send_file(
+        self,
+        file: str | Path,
+        title: str | None = None,
+        priority: _MessagePriority = _MessagePriority.DEFAULT,
+        tags: list[str] | None = None,
+        actions: list[_ViewAction | _BroadcastAction | _HttpAction] | None = None,
+        schedule: datetime | None = None,
+        timeout_seconds: int = 30,
+        email: str | None = None,
+    ) -> dict:
+        """Send a file to the server."""
+        return _send_file(
+            self,
+            file=file,
+            title=title,
+            priority=priority,
+            tags=tags,
+            actions=actions,
+            schedule=schedule,
+            timeout_seconds=timeout_seconds,
+            email=email,
+        )
+
+    def get_cached_messages(
+        self,
+        since: str = "all",
+        scheduled: bool = False,
+        timeout_seconds: int = 10,
+    ) -> list[dict]:
+        """Get cached messages from the server."""
+        return _get_cached_messages(
+            self,
+            since=since,
+            scheduled=scheduled,
+            timeout_seconds=timeout_seconds,
+        )

python_ntfy-0.8.0/python_ntfy/__init__.py

@@ -1,3 +0,0 @@
-from ._ntfy import NtfyClient as NtfyClient
-
-__all__ = ["NtfyClient"]

python_ntfy-0.8.0/python_ntfy/_ntfy.py

@@ -1,134 +0,0 @@
-"""This module provides the NtfyClient class for interacting with the ntfy notification service.
-
-The NtfyClient class allows users to send notifications, files, and perform various actions
-through the ntfy.sh service. It also supports retrieving cached messages.
-
-Typical usage example:
-
-    client = NtfyClient(topic="my_topic")
-    client.send("Hello, World!")
-"""
-
-import os
-
-from ._get_functions import get_cached_messages
-from ._send_functions import (
-    BroadcastAction,
-    HttpAction,
-    MessagePriority,
-    ViewAction,
-    send,
-    send_file,
-)
-
-
-class GetFunctionsMixin:
-    """Mixin for getting messages."""
-
-    get_cached_messages = get_cached_messages
-
-
-class SendFunctionsMixin:
-    """Mixin for sending messages."""
-
-    send = send
-    send_file = send_file
-    BroadcastAction = BroadcastAction
-    HttpAction = HttpAction
-    MessagePriority = MessagePriority
-    ViewAction = ViewAction
-
-
-class NtfyClient(GetFunctionsMixin, SendFunctionsMixin):
-    """A class for interacting with the ntfy notification service."""
-
-    def __init__(
-        self,
-        topic: str,
-        server: str = "https://ntfy.sh",
-        auth: tuple[str, str] | str | None = None,
-    ) -> None:
-        """Itinialize the NtfyClient.
-
-        Args:
-            topic: The topic to use for this client
-            server: The server to connect to. Must include the protocol (http/https)
-            auth: The authentication credentials to use for this client. Takes precedence over environment variables. Can be a tuple of (user, password) or a token.
-
-        Returns:
-            None
-
-        Exceptions:
-            None
-
-        Examples:
-            client = NtfyClient(topic="my_topic")
-        """
-        self._server = os.environ.get("NTFY_SERVER") or server
-        self._topic = topic
-        self.__set_url(self._server, topic)
-        self._auth: tuple[str, str] | None = self._resolve_auth(auth)
-
-    def _resolve_auth(
-        self, auth: tuple[str, str] | str | None
-    ) -> tuple[str, str] | None:
-        """Resolve the authentication credentials.
-
-        Args:
-            auth: The authentication credentials to use for this client. Takes precedence over environment variables. Can be a tuple of (user, password) or a token string.
-
-        Returns:
-            tuple[str, str] | None: The authentication credentials.
-        """
-        # If the user has supplied credentials, use them (including empty string)
-        if auth is not None:
-            if isinstance(auth, tuple):
-                return auth
-            if isinstance(auth, str):
-                return ("", auth)
-
-        # Otherwise, check environment variables
-        user = os.environ.get("NTFY_USER")
-        password = os.environ.get("NTFY_PASSWORD")
-        token = os.environ.get("NTFY_TOKEN")
-
-        if user and password:
-            return (user, password)
-
-        if token:
-            return ("", token)
-
-        # If no credentials are found, return None
-        return None
-
-    def __set_url(
-        self,
-        server,
-        topic,
-    ) -> None:
-        self.url = server.strip("/") + "/" + topic
-
-    def set_topic(
-        self,
-        topic: str,
-    ) -> None:
-        """Set a new topic for the client.
-
-        Args:
-            topic: The topic to set for this client.
-
-        Returns:
-            None
-        """
-        self._topic = topic
-        self.__set_url(self._server, self._topic)
-
-    def get_topic(
-        self,
-    ) -> str:
-        """Get the current topic.
-
-        Returns:
-            str: The current topic.
-        """
-        return self._topic