python-ntfy 0.1.0__tar.gz → 0.2.1__tar.gz

python_ntfy-0.2.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.1
+Name: python-ntfy
+Version: 0.2.1
+Summary: An ntfy library aiming for feature completeness
+Author: Matthew Cane
+Author-email: matthew.cane0@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# A Python Library For ntfy.sh
+
+An easy-to-use ntfy python library. Aiming for full feature support.
+
+## Quickstart
+
+1. Install using pip with `pip3 install python-ntfy`
+2. Configure the following environment variables:
+   - `NTFY_USER`: The username for your server (if required)
+   - `NTFY_PASSWORD`: The password for your server (if required)
+   - `NTFY_SERVER`: The server URL (defaults to https://ntft.sh)
+3. Setup your application to use the library:
+
+ ```python
+ # Import the ntfy client
+from python_ntfy import NtfyClient
+
+# Create an `NtfyClient` instance with a topic
+client = NtfyClient(topic="Your topic")
+
+# Send a message
+client.send("Your message here")
+```
+
+## Supported Features
+
+- Username + password auth
+- Custom servers
+- Sending plaintext messages
+- Sending Markdown formatted text messages
+- Retrieving cached messages
+- Scheduled delivery
+
+## Future Features
+
+- Access token auth
+- Email notifications
+- Tags
+- Action buttons
+- Send to multiple topics at once
+
+## Test and Development
+
+This project uses:
+
+- Poetry as it's dependency manager
+- Ruff for linting and code formatting
+
+To install dev dependencies, run `poetry install --with dev`.
+
+### Linting and Formatting
+
+These can be run with:
+
+- `poetry run ruff format`
+- `poetry run ruff check`
+
+### Tests
+
+This project is aiming for 95% code coverage. Any added features must include comprihensive tests.
+
+You can run the tests against a local instance of `ntfy` *or* `ntfy.sh`.
+
+#### Setup Steps
+
+1. To test against a *local* `ntfy` instance:
+  i. Create a container using `docker run -p 80:80 -it binwiederhier/ntfy serve --attachment-cache-dir=/cache --base-url=http://localhost`
+  ii. Set the following key in the `.env` file: `NTFY_SERVER=http://localhost`
+  iii. Add a dummy username and password to `.env` (see example.env)
+2. To test against https://ntfy.sh:
+  i. Add username and password for ntfy.sh to `.env` (see example.env)
+3. Run the tests with `poetry run pytest --cov`
+
+The tests will sent messages to the `python_ntfy_testing` topic so you will need to subcribe to that topic to see the test messages.

python_ntfy-0.2.1/README.md

@@ -0,0 +1,74 @@
+# A Python Library For ntfy.sh
+
+An easy-to-use ntfy python library. Aiming for full feature support.
+
+## Quickstart
+
+1. Install using pip with `pip3 install python-ntfy`
+2. Configure the following environment variables:
+   - `NTFY_USER`: The username for your server (if required)
+   - `NTFY_PASSWORD`: The password for your server (if required)
+   - `NTFY_SERVER`: The server URL (defaults to https://ntft.sh)
+3. Setup your application to use the library:
+
+ ```python
+ # Import the ntfy client
+from python_ntfy import NtfyClient
+
+# Create an `NtfyClient` instance with a topic
+client = NtfyClient(topic="Your topic")
+
+# Send a message
+client.send("Your message here")
+```
+
+## Supported Features
+
+- Username + password auth
+- Custom servers
+- Sending plaintext messages
+- Sending Markdown formatted text messages
+- Retrieving cached messages
+- Scheduled delivery
+
+## Future Features
+
+- Access token auth
+- Email notifications
+- Tags
+- Action buttons
+- Send to multiple topics at once
+
+## Test and Development
+
+This project uses:
+
+- Poetry as it's dependency manager
+- Ruff for linting and code formatting
+
+To install dev dependencies, run `poetry install --with dev`.
+
+### Linting and Formatting
+
+These can be run with:
+
+- `poetry run ruff format`
+- `poetry run ruff check`
+
+### Tests
+
+This project is aiming for 95% code coverage. Any added features must include comprihensive tests.
+
+You can run the tests against a local instance of `ntfy` *or* `ntfy.sh`.
+
+#### Setup Steps
+
+1. To test against a *local* `ntfy` instance:
+  i. Create a container using `docker run -p 80:80 -it binwiederhier/ntfy serve --attachment-cache-dir=/cache --base-url=http://localhost`
+  ii. Set the following key in the `.env` file: `NTFY_SERVER=http://localhost`
+  iii. Add a dummy username and password to `.env` (see example.env)
+2. To test against https://ntfy.sh:
+  i. Add username and password for ntfy.sh to `.env` (see example.env)
+3. Run the tests with `poetry run pytest --cov`
+
+The tests will sent messages to the `python_ntfy_testing` topic so you will need to subcribe to that topic to see the test messages.

{python_ntfy-0.1.0 → python_ntfy-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-ntfy"
-version = "0.1.0"
+version = "0.2.1"
 description = "An ntfy library aiming for feature completeness"
 authors = ["Matthew Cane <matthew.cane0@gmail.com>"]
 readme = "README.md"
@@ -9,11 +9,12 @@ readme = "README.md"
 python = "^3.11"
 requests = "^2.31.0"
 
-[tool.poetry.group.test.dependencies]
+[tool.poetry.group.dev.dependencies]
 pytest = "^7.4.1"
 python-dotenv = "^1.0.0"
 pytest-asyncio = "^0.21.1"
 pytest-codecov = "^0.5.1"
+ruff = "^0.7.0"
 
 [build-system]
 requires = ["poetry-core"]

{python_ntfy-0.1.0 → python_ntfy-0.2.1}/python_ntfy/__init__.py

@@ -2,7 +2,14 @@ import os
 
 
 class NtfyClient:
-    from ._send_functions import send, send_file
+    from ._send_functions import (
+        send,
+        send_file,
+        MessagePriority,
+        ViewAction,
+        BroadcastAction,
+        HttpAction,
+    )
     from ._get_functions import get_cached_messages
 
     def __init__(
@@ -15,9 +22,9 @@ class NtfyClient:
         :param server: The server to connect to. Must include the protocol (http/https)
         :return:
         """
-        self._server = server
+        self._server = os.environ.get("NTFY_SERVER") or server
         self._topic = topic
-        self.__set_url(server, topic)
+        self.__set_url(self._server, topic)
 
         if (user := os.environ.get("NTFY_USER")) and (
             password := os.environ.get("NTFY_PASSWORD")

{python_ntfy-0.1.0 → python_ntfy-0.2.1}/python_ntfy/_get_functions.py

@@ -1,4 +1,5 @@
-import json, requests
+import json
+import requests
 
 
 def get_cached_messages(self, since: str = "all", scheduled: bool = False):

python_ntfy-0.2.1/python_ntfy/_send_functions.py

@@ -0,0 +1,202 @@
+import json
+import requests
+from enum import Enum
+from typing import Optional, Union
+
+
+class MessagePriority(Enum):
+    """
+    Ntfy message priority levels.
+    """
+
+    MIN = "1"
+    LOW = "2"
+    DEFAULT = "3"
+    HIGH = "4"
+    MAX = "5"
+    URGENT = MAX
+
+
+class ActionType(Enum):
+    """
+    Action button types
+    """
+
+    VIEW = "view"
+    BROADCAST = "broadcast"
+    HTTP = "http"
+
+
+class Action:
+    def __init__(self, label: str, url: str, clear: bool = False):
+        self.label = label
+        self.url = url
+        self.actions: list = []
+        self.clear = clear
+
+
+class ViewAction(Action):
+    def __init__(self, label: str, url: str, clear: bool = False):
+        self.action = ActionType.VIEW
+        super().__init__(label=label, url=url, clear=clear)
+
+    def to_dict(self):
+        return {
+            "action": self.action.value,
+            "label": self.label,
+            "url": self.url,
+            "clear": self.clear,
+        }
+
+    def to_header(self):
+        return f"action={self.action.value}, label={self.label}, url={self.url}, clear={self.clear}"
+
+
+class BroadcastAction(Action):
+    def __init__(
+        self,
+        label: str,
+        intent: str = "io.heckel.ntfy.USER_ACTION",
+        extras: Optional[dict] = None,
+        clear: bool = False,
+    ):
+        self.action = ActionType.BROADCAST
+        self.intent = intent
+        self.extras = extras
+        super().__init__(label, ActionType.BROADCAST, clear)
+
+    def to_dict(self):
+        return {
+            "action": self.action.value,
+            "label": self.label,
+            "extras": self.extras,
+            "clear": self.clear,
+        }
+
+    def to_header(self):
+        extras = ""
+        if self.extras is not None:
+            for key, value in self.extras.items():
+                extras += f"{key}={value},"
+        return f"action={self.action.value}, label={self.label}, url={self.url}, clear={self.clear}"
+
+
+class HttpAction(Action):
+    def __init__(
+        self,
+        label: str,
+        url: str,
+        method: str = "POST",
+        headers: Optional[dict] = None,
+        body: Optional[str] = None,
+        clear: bool = False,
+    ):
+        self.action = ActionType.HTTP
+        self.method = method
+        self.headers = headers
+        self.body = body
+        super().__init__(label, url, clear)
+
+    def to_dict(self):
+        action_dict = {
+            "action": self.action.value,
+            "label": self.label,
+            "url": self.url,
+            "method": self.method,
+            "clear": self.clear,
+        }
+        if self.headers:
+            action_dict["headers"] = self.headers
+        if self.body:
+            action_dict["body"] = self.body
+        return action_dict
+
+    def to_header(self):
+        header_str = f"action={self.action.value}, label={self.label}, url={self.url}, method={self.method}, clear={self.clear}"
+        if self.headers is not None:
+            headers = ""
+            for key, value in self.headers.items():
+                headers += f"headers.{key}={value}"
+            header_str += f", {headers}"
+        if self.body:
+            header_str += f", body={self.body}"
+        print(header_str)
+        return header_str
+
+
+def send(
+    self,
+    message: str,
+    title: str = None,
+    priority: Optional[MessagePriority] = MessagePriority.DEFAULT,
+    tags: list = [],
+    actions: list[Union[ViewAction, BroadcastAction, HttpAction, None]] = [],
+    format_as_markdown: bool = False,
+):
+    """
+    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)
+    """
+    headers = {
+        "Title": title,
+        "Priority": priority.value,
+        "Tags": ",".join(tags),
+        "Markdown": "true" if format_as_markdown else "false",
+    }
+    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 response
+
+
+def send_file(
+    self,
+    file: str,
+    title: str = None,
+    priority: Optional[MessagePriority] = MessagePriority.DEFAULT,
+    tags: list = [],
+    actions: list[Union[ViewAction, BroadcastAction, HttpAction, None]] = [],
+):
+    """
+    Send 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
+
+    :examples:
+    response = client.send_file(file_path="example.txt")
+    """
+    headers = {
+        "Title": title,
+        "Filename": file.split("/")[-1],
+        "Priority": priority.value,
+        "Tags": ",".join(tags),
+        "Actions": " ; ".join([action.to_header() for action in actions]),
+    }
+
+    with open(file, "rb") as file:
+        response = json.loads(
+            requests.post(
+                url=self.url, data=file, headers=headers, auth=self._auth
+            ).text
+        )
+    return response

python_ntfy-0.1.0/PKG-INFO

@@ -1,69 +0,0 @@
-Metadata-Version: 2.1
-Name: python-ntfy
-Version: 0.1.0
-Summary: An ntfy library aiming for feature completeness
-Author: Matthew Cane
-Author-email: matthew.cane0@gmail.com
-Requires-Python: >=3.11,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Requires-Dist: requests (>=2.31.0,<3.0.0)
-Description-Content-Type: text/markdown
-
-# ntfy.sh Python Library
-
-An easy-to-use ntfy python library. Aiming for full feature support.
-
-## Quickstart
-
-1. Install using pip with `pip3 install python-ntfy`
-2. If you are using a server that requires auth, set the env vars
-3. Import the library
-
- ```python
-from python_ntfy import NtfyClient
- ```
-
-4. Create an `NtfyClient` instance with a topic
-
-```python
-client = NtfyClient(topic="Your topic")
-```
-
-5. Send a message
-
-```python
-client.send("Your message here")
-```
-
-## Supported Features
-
-- Username + password auth
-- Custom servers
-- Sending plaintext messages
-- Sending Markdown formatted text messages
-- Retrieving cached messages
-- Scheduled delivery
-
-## Future Features
-
-- Access token auth
-- Email notifications
-- Tags
-- Action buttons
-- Send to multiple topics at once
-
-## Test and Development
-
-This project uses Poetry. 
-
-### Tests
-
-This project is aiming for 95% code coverage. Any added features must include comprihensive tests.
-
-To run tests:
-
-1. `poetry install --include test`
-2. Add username and password for ntfy.sh to `.env`
-3. `poetry run pytest --cov`
-

python_ntfy-0.1.0/README.md

@@ -1,56 +0,0 @@
-# ntfy.sh Python Library
-
-An easy-to-use ntfy python library. Aiming for full feature support.
-
-## Quickstart
-
-1. Install using pip with `pip3 install python-ntfy`
-2. If you are using a server that requires auth, set the env vars
-3. Import the library
-
- ```python
-from python_ntfy import NtfyClient
- ```
-
-4. Create an `NtfyClient` instance with a topic
-
-```python
-client = NtfyClient(topic="Your topic")
-```
-
-5. Send a message
-
-```python
-client.send("Your message here")
-```
-
-## Supported Features
-
-- Username + password auth
-- Custom servers
-- Sending plaintext messages
-- Sending Markdown formatted text messages
-- Retrieving cached messages
-- Scheduled delivery
-
-## Future Features
-
-- Access token auth
-- Email notifications
-- Tags
-- Action buttons
-- Send to multiple topics at once
-
-## Test and Development
-
-This project uses Poetry. 
-
-### Tests
-
-This project is aiming for 95% code coverage. Any added features must include comprihensive tests.
-
-To run tests:
-
-1. `poetry install --include test`
-2. Add username and password for ntfy.sh to `.env`
-3. `poetry run pytest --cov`

python_ntfy-0.1.0/python_ntfy/_send_functions.py

@@ -1,48 +0,0 @@
-import json, requests
-
-
-def send(self, message: str, title: str = None, format_as_markdown: bool = False):
-    """
-    Send a text based message to the server
-
-    :param message: The message to send
-    :param title: The title of the message. Optional
-    :param format_as_markdown: If true, the message will be formatted as markdown. Optional
-    :return: The response from the server
-
-    :examples:
-    response = client.send(message="Example message")
-    response = client.send(message="Example message", title="Example title")
-    response = client.send(message="*Example markdown*", format_as_markdown=True)
-    """
-    headers = {
-        "Title": title,
-        "Markdown": "true" if format_as_markdown else "false",
-    }
-
-    response = json.loads(
-        requests.post(url=self.url, data=message, headers=headers, auth=self._auth).text
-    )
-    return response
-
-
-def send_file(self, file: str, title: str = None):
-    """
-    Send a file to the server
-
-    :param file_path: The path to the file to send
-    :param title: The title of the file. Optional
-    :return: The response from the server
-
-    :examples:
-    response = client.send_file(file_path="example.txt")
-    """
-    headers = {"Title": title, "Filename": file.split("/")[-1]}
-
-    with open(file, "rb") as file:
-        response = json.loads(
-            requests.post(
-                url=self.url, data=file, headers=headers, auth=self._auth
-            ).text
-        )
-    return response