python-ntfy 0.2.5__tar.gz → 0.3.6__tar.gz

{python_ntfy-0.2.5 → python_ntfy-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-ntfy
-Version: 0.2.5
+Version: 0.3.6
 Summary: An ntfy library aiming for feature completeness
 Home-page: https://github.com/MatthewCane/python-ntfy
 License: MIT
@@ -20,9 +20,13 @@ Project-URL: Documentation, https://matthewcane.github.io/python-ntfy/
 Project-URL: Repository, https://github.com/MatthewCane/python-ntfy
 Description-Content-Type: text/markdown
 
-# A Python Library For ntfy.sh
+# A Python Library For ntfy
 
-An easy-to-use ntfy python library. Aiming for full feature support.
+![PyPI - Version](https://img.shields.io/pypi/v/python-ntfy?link=https%3A%2F%2Fpypi.org%2Fproject%2Fpython-ntfy%2F)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/python-ntfy?link=https%3A%2F%2Fpypistats.org%2Fpackages%2Fpython-ntfy)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MatthewCane/python-ntfy/publish.yml?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.
 
 ## Quickstart
 
@@ -49,6 +53,7 @@ See the full documentation site at [https://matthewcane.github.io/python-ntfy/](
 ## Supported Features
 
 - Username + password auth
+- Access token auth
 - Custom servers
 - Sending plaintext messages
 - Sending Markdown formatted text messages
@@ -59,8 +64,7 @@ See the full documentation site at [https://matthewcane.github.io/python-ntfy/](
 
 ## Future Features
 
-- Access token auth
-- Email notifications
+- [Email notifications](https://docs.ntfy.sh/publish/#e-mail-notifications)
 - Send to multiple topics at once
 
 ## Testing and Development

{python_ntfy-0.2.5 → python_ntfy-0.3.6}/README.md

@@ -1,6 +1,10 @@
-# A Python Library For ntfy.sh
+# A Python Library For ntfy
 
-An easy-to-use ntfy python library. Aiming for full feature support.
+![PyPI - Version](https://img.shields.io/pypi/v/python-ntfy?link=https%3A%2F%2Fpypi.org%2Fproject%2Fpython-ntfy%2F)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/python-ntfy?link=https%3A%2F%2Fpypistats.org%2Fpackages%2Fpython-ntfy)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/MatthewCane/python-ntfy/publish.yml?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.
 
 ## Quickstart
 
@@ -27,6 +31,7 @@ See the full documentation site at [https://matthewcane.github.io/python-ntfy/](
 ## Supported Features
 
 - Username + password auth
+- Access token auth
 - Custom servers
 - Sending plaintext messages
 - Sending Markdown formatted text messages
@@ -37,8 +42,7 @@ See the full documentation site at [https://matthewcane.github.io/python-ntfy/](
 
 ## Future Features
 
-- Access token auth
-- Email notifications
+- [Email notifications](https://docs.ntfy.sh/publish/#e-mail-notifications)
 - Send to multiple topics at once
 
 ## Testing and Development

python_ntfy-0.3.6/pyproject.toml

@@ -0,0 +1,74 @@
+[tool.poetry]
+name = "python-ntfy"
+version = "0.3.6"
+description = "An ntfy library aiming for feature completeness"
+authors = ["Matthew Cane <matthew.cane0@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+repository = "https://github.com/MatthewCane/python-ntfy"
+documentation = "https://matthewcane.github.io/python-ntfy/"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+requests = "^2.31.0"
+mypy = "^1.12.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.4.1,<9.0.0"
+python-dotenv = "^1.0.0"
+pytest-asyncio = ">=0.21.1,<0.25.0"
+pytest-codecov = ">=0.5.1,<0.7.0"
+ruff = "^0.7.0"
+mkdocs-material = "^9.5.41"
+mkdocstrings-python = "^1.12.1"
+types-pygments = "^2.18.0.20240506"
+types-colorama = "^0.4.15.20240311"
+types-requests = "^2.32.0.20241016"
+types-setuptools = "^75.2.0.20241018"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff.lint]
+select = [
+    "E",    # PycodeStyle errors
+    "W",    # PycodeStyle warnings
+    "F",    # PyFlakes
+    "I",    # Isort
+    "N",    # pep8-naming
+    "D",    # Pydocstyle
+    "UP",   # PyUpgrade
+    "ANN",  # Flake8-annotations
+    "S",    # Flake8-bandit
+    "BLE",  # Flake8-blind-except
+    "B",    # Flake8-bugbear
+    "A",    # Flake8-builtins
+    "C4",   # Flake8-comprehensions
+    "T10",  # Flake8-debugger
+    "EM",   # Flake8-errmessages
+    "Q",    # Flake8-quotes
+    "RET",  # Flake8-return
+    "TRY",  # Triceratops
+    "FURB", # Refurb
+    "RUF",  # Ruff
+    "PERF", # Perflint
+]
+ignore = [
+    "E501",   # Line too long
+    "D103",   # Missing docstring in public function
+    "D417",   # Undocumented parameters
+    "D104",   # First line of docstring should be in imperative moof
+    "D100",   # Missing docstring in public module
+    "ANN001", # Missing type annotation for function argument
+    "ANN101", # Missing type annotation for self in method
+    "S101",   # Use of assert detected
+]
+
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

python_ntfy-0.3.6/python_ntfy/__init__.py

@@ -0,0 +1,90 @@
+"""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
+
+
+class NtfyClient:
+    """A class for interacting with the ntfy notification service."""
+
+    # The functions need to be imported here to:
+    # 1. Keep the functions in a separate file
+    # 2. Keep the docstrings working in the IDE
+    # 3. Allow the functions to be called with self
+    # MyPy does not like this, but it works
+    from ._get_functions import get_cached_messages  # type: ignore
+    from ._send_functions import (  # type: ignore
+        BroadcastAction,
+        HttpAction,
+        MessagePriority,
+        ViewAction,
+        send,
+        send_file,
+    )
+
+    def __init__(
+        self,
+        topic: str,
+        server: str = "https://ntfy.sh",
+    ) -> 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)
+
+        Returns:
+            None
+
+        Exceptions:
+            ToDo
+
+        Examples:
+            client = NtfyClient(topic="my_topic")
+        """
+        self._server = os.environ.get("NTFY_SERVER") or server
+        self._topic = topic
+        self.__set_url(self._server, topic)
+
+        # If the user has set the user and password, use that
+        # If the user has set the token, use that
+        # Otherwise, use an empty user and token
+        if (user := os.environ.get("NTFY_USER")) and (
+            password := os.environ.get("NTFY_PASSWORD")
+        ):
+            self._auth = (user, password)
+        elif token := os.environ.get("NTFY_TOKEN"):
+            self._auth = ("", token)
+        else:
+            self._auth = ("", "")
+
+    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

python_ntfy-0.3.6/python_ntfy/_get_functions.py

@@ -0,0 +1,46 @@
+import json
+
+import requests
+
+
+def get_cached_messages(
+    self,
+    since: str = "all",
+    scheduled: bool = False,
+    timeout_seconds: int = 10,
+) -> list[dict]:
+    """Get cached messages from the server.
+
+    Args:
+        since: The timestamp to start from. If set to "all", will return all messages.
+        scheduled: If true, will return scheduled messages.
+        timeout_seconds: The number of seconds to wait for the response.
+
+    Returns:
+        A list of messages.
+
+    Examples:
+        response = client.get(since="all")
+        response = client.get(since="all", scheduled=True)
+        response = client.get(since="2019-01-01")
+        response = client.get(since="2019-01-01", scheduled=True)
+    """
+    params = {"poll": "1"}
+    if scheduled:
+        params.update({"scheduled": str(scheduled)})
+    if since:
+        params.update({"since": since})
+
+    response = [
+        json.loads(line)
+        for line in requests.get(
+            url=self.url + "/json",
+            params=params,
+            auth=self._auth,
+            timeout=timeout_seconds,
+        )
+        .text.strip()
+        .splitlines()
+    ]
+    # Reverse the list so that the most recent notification is first
+    return sorted(response, key=lambda x: x["time"], reverse=True)

{python_ntfy-0.2.5 → python_ntfy-0.3.6}/python_ntfy/_send_functions.py

@@ -1,13 +1,13 @@
 import json
-import requests
 from enum import Enum
+from pathlib import Path
 from typing import Optional, Union
 
+import requests
+
 
 class MessagePriority(Enum):
-    """
-    Ntfy message priority levels.
-    """
+    """Ntfy message priority levels."""
 
     MIN = "1"
     LOW = "2"
@@ -18,9 +18,7 @@ class MessagePriority(Enum):
 
 
 class ActionType(Enum):
-    """
-    Action button types
-    """
+    """Action button types."""
 
     VIEW = "view"
     BROADCAST = "broadcast"
@@ -28,7 +26,7 @@ class ActionType(Enum):
 
 
 class Action:
-    def __init__(self, label: str, url: str, clear: bool = False):
+    def __init__(self, label: str, url: str, clear: bool = False) -> None:
         self.label = label
         self.url = url
         self.actions: list = []
@@ -36,7 +34,7 @@ class Action:
 
 
 class ViewAction(Action):
-    def __init__(self, label: str, url: str, clear: bool = False):
+    def __init__(self, label: str, url: str, clear: bool = False) -> None:
         self.action = ActionType.VIEW
         super().__init__(label=label, url=url, clear=clear)
 
@@ -59,7 +57,7 @@ class BroadcastAction(Action):
         intent: str = "io.heckel.ntfy.USER_ACTION",
         extras: Optional[dict[str, str]] = None,
         clear: bool = False,
-    ):
+    ) -> None:
         self.action = ActionType.BROADCAST
         self.intent = intent
         self.extras = extras
@@ -94,7 +92,7 @@ class HttpAction(Action):
         headers: Optional[dict[str, str]] = None,
         body: Optional[str] = None,
         clear: bool = False,
-    ):
+    ) -> None:
         self.action = ActionType.HTTP
         self.method = method
         self.headers = headers
@@ -133,26 +131,42 @@ def send(
     message: str,
     title: Optional[str] = None,
     priority: MessagePriority = MessagePriority.DEFAULT,
-    tags: list = [],
-    actions: list[Union[ViewAction, BroadcastAction, HttpAction]] = [],
+    tags: Optional[list] = None,
+    actions: Optional[list[Union[ViewAction, BroadcastAction, HttpAction]]] = None,
     format_as_markdown: bool = False,
+    timeout_seconds: int = 5,
 ) -> dict:
+    """Send a text-based message to the server.
+
+    Call this function to send a message to the server. The message will be sent
+    to the server and then broadcast to all clients subscribed to the topic.
+
+    Args:
+        message: The message to send.
+        title: The title of the message.
+        priority: The priority of the message.
+        tags: A list of tags to attach to the message. Can be an emoji short code.
+        actions: A list of Actions objects to attach to the message.
+        format_as_markdown: If true, the message will be formatted as markdown.
+        additional_topics: A list of additional topics to send the message to.
+        timeout_seconds: The number of seconds to wait before timing out.
+
+    Returns:
+        dict: The response from the server.
+
+    Raises:
+        ToDo
+
+    Examples:
+        response = client.send(message="Example message")
+        response = client.send(message="Example message", title="Example title", priority=MessagePriority.HIGH, tags=["fire", "warning"])
+        response = client.send(message="*Example markdown*", format_as_markdown=True)
     """
-    Send a text based message to the server
-
-    :param message: The message to send
-    :param title: The title of the message. Optional
-    :param priority: The priority of the message. Optional, defaults to MessagePriority.DEFAULT
-    :param tags: A list of tags to attach to the message. Can be an emoji short code. Optional
-    :param format_as_markdown: If true, the message will be formatted as markdown. Optional
-    :param actions: A list of Actions objects to attach to the message. Optional
-    :return: The response from the server
-
-    :examples:
-    response = client.send(message="Example message")
-    response = client.send(message="Example message", title="Example title", priority=MessagePriority.HIGH, tags=["fire", "warning"])
-    response = client.send(message="*Example markdown*", format_as_markdown=True)
-    """
+    if tags is None:
+        tags = []
+    if actions is None:
+        actions = []
+
     headers = {
         "Title": title,
         "Priority": priority.value,
@@ -162,10 +176,15 @@ def send(
     if len(actions) > 0:
         headers["Actions"] = " ; ".join([action.to_header() for action in actions])
 
-    response = json.loads(
-        requests.post(url=self.url, data=message, headers=headers, auth=self._auth).text
+    return json.loads(
+        requests.post(
+            url=self.url,
+            data=message,
+            headers=headers,
+            auth=self._auth,
+            timeout=timeout_seconds,
+        ).text,
     )
-    return response
 
 
 def send_file(
@@ -173,22 +192,34 @@ def send_file(
     file: str,
     title: Optional[str] = None,
     priority: MessagePriority = MessagePriority.DEFAULT,
-    tags: list = [],
-    actions: list[Union[ViewAction, BroadcastAction, HttpAction]] = [],
+    tags: Optional[list] = None,
+    actions: Optional[list[Union[ViewAction, BroadcastAction, HttpAction]]] = None,
+    timeout_seconds: int = 30,
 ) -> dict:
-    """
-    Send a file to the server
+    """Sends a file to the server.
 
-    :param file_path: The path to the file to send.
-    :param title: The title of the file. Optional
-    :param priority: The priority of the message. Optional, defaults to MessagePriority.DEFAULT
-    :param tags: A list of tags to attach to the message. Can be an emoji short code. Optional
-    :param actions: A list of ActionButton objects to attach to the message. Optional
-    :return: The response from the server
+    Args:
+        file: The path to the file to send.
+        title: The title of the file.
+        priority: The priority of the message. Optional, defaults to MessagePriority.
+        tags: A list of tags to attach to the message. Can be an emoji short code.
+        actions: A list of ActionButton objects to attach to the message.
+        timeout_seconds: The number of seconds to wait before timing out.
 
-    :examples:
-    response = client.send_file(file_path="example.txt")
+    Returns:
+        dict: The response from the server.
+
+    Raises:
+        ToDo
+
+    Examples:
+        response = client.send_file(file="example.txt")
     """
+    if actions is None:
+        actions = []
+    if tags is None:
+        tags = []
+
     headers = {
         "Title": str(title),
         "Filename": file.split("/")[-1],
@@ -197,8 +228,13 @@ def send_file(
         "Actions": " ; ".join([action.to_header() for action in actions]),
     }
 
-    with open(file, "rb") as f:
-        response = json.loads(
-            requests.post(url=self.url, data=f, headers=headers, auth=self._auth).text
+    with Path(file).open("rb") as f:
+        return json.loads(
+            requests.post(
+                url=self.url,
+                data=f,
+                headers=headers,
+                auth=self._auth,
+                timeout=timeout_seconds,
+            ).text,
         )
-    return response

python_ntfy-0.2.5/pyproject.toml

@@ -1,35 +0,0 @@
-[tool.poetry]
-name = "python-ntfy"
-version = "0.2.5"
-description = "An ntfy library aiming for feature completeness"
-authors = ["Matthew Cane <matthew.cane0@gmail.com>"]
-readme = "README.md"
-license = "MIT"
-repository = "https://github.com/MatthewCane/python-ntfy"
-documentation = "https://matthewcane.github.io/python-ntfy/"
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers"
-]
-
-[tool.poetry.dependencies]
-python = "^3.11"
-requests = "^2.31.0"
-mypy = "^1.12.0"
-
-[tool.poetry.group.dev.dependencies]
-pytest = ">=7.4.1,<9.0.0"
-python-dotenv = "^1.0.0"
-pytest-asyncio = ">=0.21.1,<0.25.0"
-pytest-codecov = ">=0.5.1,<0.7.0"
-ruff = "^0.7.0"
-mkdocs-material = "^9.5.41"
-mkdocstrings-python = "^1.12.1"
-types-pygments = "^2.18.0.20240506"
-types-colorama = "^0.4.15.20240311"
-types-requests = "^2.32.0.20241016"
-types-setuptools = "^75.2.0.20241018"
-
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"

python_ntfy-0.2.5/python_ntfy/__init__.py

@@ -1,61 +0,0 @@
-import os
-
-
-class NtfyClient:
-    # The functions need to be imported here to:
-    # 1. Keep the functions in a separate file
-    # 2. Keep the docstrings working in the IDE
-    # 3. Allow the functions to be called with self
-    # MyPy does not like this, but it works
-    from ._send_functions import (  # type: ignore
-        send,
-        send_file,
-        MessagePriority,
-        ViewAction,
-        BroadcastAction,
-        HttpAction,
-    )
-    from ._get_functions import get_cached_messages  # type: ignore
-
-    def __init__(
-        self,
-        topic: str,
-        server: str = "https://ntfy.sh",
-    ) -> None:
-        """
-        :param topic: The topic to use for this client
-        :param server: The server to connect to. Must include the protocol (http/https)
-        :return None:
-        """
-
-        self._server = os.environ.get("NTFY_SERVER") or server
-        self._topic = topic
-        self.__set_url(self._server, topic)
-
-        if (user := os.environ.get("NTFY_USER")) and (
-            password := os.environ.get("NTFY_PASSWORD")
-        ):
-            self._auth = (user, password)
-        else:
-            self._auth = ("", "")
-
-    def __set_url(self, server, topic):
-        self.url = server.strip("/") + "/" + topic
-
-    def set_topic(self, topic: str):
-        """
-        Set a new topic for the client
-
-        :param topic: The topic to use for this client
-        :return: None
-        """
-        self._topic = topic
-        self.__set_url(self._server, self._topic)
-
-    def get_topic(self):
-        """
-        Get the current topic
-
-        :return: str
-        """
-        return self._topic

python_ntfy-0.2.5/python_ntfy/_get_functions.py

@@ -1,35 +0,0 @@
-import json
-import requests
-
-
-def get_cached_messages(
-    self, since: str = "all", scheduled: bool = False
-) -> list[dict]:
-    """
-    Get cached messages from the server
-
-    :param since: The timestamp to start from. If set to "all", will return all messages. Optional
-    :param scheduled: If true, will return scheduled messages. Optional
-    :return: A list of messages
-
-    :examples:
-    response = client.get(since="all")
-    response = client.get(since="all", scheduled=True)
-    response = client.get(since="2019-01-01")
-    response = client.get(since="2019-01-01", scheduled=True)
-    """
-
-    params = {"poll": "1"}
-    if scheduled:
-        params.update({"scheduled": str(scheduled)})
-    if since:
-        params.update({"since": since})
-
-    response = [
-        json.loads(line)
-        for line in requests.get(url=self.url + "/json", params=params, auth=self._auth)
-        .text.strip()
-        .splitlines()
-    ]
-    # Reverse the list so that the most recent notification is first
-    return sorted(response, key=lambda x: x["time"], reverse=True)