python-ntfy 0.8.1__tar.gz → 0.9.1__tar.gz

{python_ntfy-0.8.1 → python_ntfy-0.9.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-ntfy
-Version: 0.8.1
-Summary: An ntfy library aiming for feature completeness
+Version: 0.9.1
+Summary: An easy-to-use library for the ntfy notification service.
 Keywords: ntfy,notifications,push,http,api
 Author: Matthew Cane
 Author-email: Matthew Cane <matthew.cane0@gmail.com>
@@ -18,32 +18,18 @@ Classifier: Topic :: Communications
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: requests>=2.31.0
-Requires-Dist: mkdocstrings[python]>=0.26.2,<0.31.0 ; extra == 'dev'
-Requires-Dist: mypy>=1.12.0,<2.0.0 ; extra == 'dev'
-Requires-Dist: pytest>=7.4.1,<9.0.0 ; extra == 'dev'
-Requires-Dist: python-dotenv>=1.0.0,<2.0.0 ; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.1,<1.2.0 ; extra == 'dev'
-Requires-Dist: pytest-codecov>=0.5.1,<0.8.0 ; extra == 'dev'
-Requires-Dist: ruff>=0.7,<0.13 ; extra == 'dev'
-Requires-Dist: mkdocs-material>=9.5.41,<10.0.0 ; extra == 'dev'
-Requires-Dist: mkdocstrings-python>=1.12.1,<2.0.0 ; extra == 'dev'
-Requires-Dist: types-pygments>=2.18.0.20240506 ; extra == 'dev'
-Requires-Dist: types-colorama>=0.4.15.20240311 ; extra == 'dev'
-Requires-Dist: types-requests>=2.32.0.20241016 ; extra == 'dev'
-Requires-Dist: types-setuptools>=75.2.0.20241018,<81.0.0.0 ; extra == 'dev'
 Requires-Python: >=3.12, <3.14
 Project-URL: Changelog, https://github.com/matthewcane/python-ntfy/releases
-Project-URL: Documentation, https://python-ntfy.readthedocs.io/
+Project-URL: Documentation, https://matthewcane.github.io/python-ntfy/
 Project-URL: Homepage, https://github.com/matthewcane/python-ntfy
 Project-URL: Issues, https://github.com/matthewcane/python-ntfy/issues
 Project-URL: Repository, https://github.com/matthewcane/python-ntfy
-Provides-Extra: dev
 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.1 → python_ntfy-0.9.1}/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.1 → python_ntfy-0.9.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "python-ntfy"
-version = "0.8.1"
-description = "An ntfy library aiming for feature completeness"
+version = "0.9.1"
+description = "An easy-to-use library for the ntfy notification service."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12, <3.14"
@@ -24,7 +24,7 @@ authors = [{ name = "Matthew Cane", email = "matthew.cane0@gmail.com" }]
 
 [project.urls]
 Homepage = "https://github.com/matthewcane/python-ntfy"
-Documentation = "https://python-ntfy.readthedocs.io/"
+Documentation = "https://matthewcane.github.io/python-ntfy/"
 Repository = "https://github.com/matthewcane/python-ntfy"
 Issues = "https://github.com/matthewcane/python-ntfy/issues"
 Changelog = "https://github.com/matthewcane/python-ntfy/releases"
@@ -37,24 +37,7 @@ build-backend = "uv_build"
 module-name = "python_ntfy"
 module-root = ""
 
-[tool.uv]
-dev-dependencies = [
-    "mkdocstrings[python]>=0.26.2,<0.31.0",
-    "mypy>=1.12.0,<2.0.0",
-    "pytest>=7.4.1,<9.0.0",
-    "python-dotenv>=1.0.0,<2.0.0",
-    "pytest-asyncio>=0.21.1,<1.2.0",
-    "pytest-codecov>=0.5.1,<0.8.0",
-    "ruff>=0.7,<0.13",
-    "mkdocs-material>=9.5.41,<10.0.0",
-    "mkdocstrings-python>=1.12.1,<2.0.0",
-    "types-pygments>=2.18.0.20240506",
-    "types-colorama>=0.4.15.20240311",
-    "types-requests>=2.32.0.20241016",
-    "types-setuptools>=75.2.0.20241018,<81.0.0.0",
-]
-
-[project.optional-dependencies]
+[dependency-groups]
 dev = [
     "mkdocstrings[python]>=0.26.2,<0.31.0",
     "mypy>=1.12.0,<2.0.0",
@@ -74,6 +57,9 @@ dev = [
 [tool.ruff]
 target-version = "py312"
 
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
 [tool.ruff.lint]
 select = [
     "E",    # PycodeStyle errors
@@ -125,3 +111,20 @@ 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.1/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.1/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.1/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.1/python_ntfy/__init__.py

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

python_ntfy-0.8.1/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