Initial commit

.gitignore

@@ -0,0 +1,6 @@
+.pytest_cache
+.venv
+__pytest__
+.env
+.coverage
+__pycache__

README.md

@@ -0,0 +1,56 @@
+# 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`

example.env

@@ -0,0 +1,2 @@
+NTFY_USER=''
+NTFY_PASSWORD=''

pyproject.toml

@@ -0,0 +1,20 @@
+[tool.poetry]
+name = "python-ntfy"
+version = "0.1.0"
+description = ""
+authors = ["Matthew Cane <[email protected]>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+requests = "^2.31.0"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^7.4.1"
+python-dotenv = "^1.0.0"
+pytest-asyncio = "^0.21.1"
+pytest-codecov = "^0.5.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

python_ntfy/__init__.py

@@ -0,0 +1,40 @@
+import os
+
+
+class NtfyClient:
+    from ._send_functions import send, send_file
+    from ._get_functions import get_cached_messages
+
+    def __init__(
+        self,
+        topic: str,
+        server: str = "https://ntfy.sh",
+    ):
+        """
+        :param topic: The topic to use for this client
+        :param server: The server to connect to. Must include the protocol (http/https)
+        :return:
+        """
+        self._server = server
+        self._topic = topic
+        self.__set_url(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)

python_ntfy/_get_functions.py

@@ -0,0 +1,32 @@
+import json, requests
+
+
+def get_cached_messages(self, since: str = "all", scheduled: bool = False):
+    """
+    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": 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)

python_ntfy/_send_functions.py

@@ -0,0 +1,48 @@
+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

tests/assets/test_markdown.md

@@ -0,0 +1,157 @@
+An h1 header
+============
+
+Paragraphs are separated by a blank line.
+
+2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists
+look like:
+
+  * this one
+  * that one
+  * the other one
+
+Note that --- not considering the asterisk --- the actual text
+content starts at 4-columns in.
+
+> Block quotes are
+> written like so.
+>
+> They can span multiple paragraphs,
+> if you like.
+
+Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all
+in chapters 12--14"). Three dots ... will be converted to an ellipsis.
+Unicode is supported. ☺
+
+
+
+An h2 header
+------------
+
+Here's a numbered list:
+
+ 1. first item
+ 2. second item
+ 3. third item
+
+Note again how the actual text starts at 4 columns in (4 characters
+from the left side). Here's a code sample:
+
+    # Let me re-iterate ...
+    for i in 1 .. 10 { do-something(i) }
+
+As you probably guessed, indented 4 spaces. By the way, instead of
+indenting the block, you can use delimited blocks, if you like:
+
+~~~
+define foobar() {
+    print "Welcome to flavor country!";
+}
+~~~
+
+(which makes copying & pasting easier). You can optionally mark the
+delimited block for Pandoc to syntax highlight it:
+
+~~~python
+import time
+# Quick, count to ten!
+for i in range(10):
+    # (but not *too* quick)
+    time.sleep(0.5)
+    print i
+~~~
+
+
+
+### An h3 header ###
+
+Now a nested list:
+
+ 1. First, get these ingredients:
+
+      * carrots
+      * celery
+      * lentils
+
+ 2. Boil some water.
+
+ 3. Dump everything in the pot and follow
+    this algorithm:
+
+        find wooden spoon
+        uncover pot
+        stir
+        cover pot
+        balance wooden spoon precariously on pot handle
+        wait 10 minutes
+        goto first step (or shut off burner when done)
+
+    Do not bump wooden spoon or it will fall.
+
+Notice again how text always lines up on 4-space indents (including
+that last line which continues item 3 above).
+
+Here's a link to [a website](http://foo.bar), to a [local
+doc](local-doc.html), and to a [section heading in the current
+doc](#an-h2-header). Here's a footnote [^1].
+
+[^1]: Footnote text goes here.
+
+Tables can look like this:
+
+size  material      color
+----  ------------  ------------
+9     leather       brown
+10    hemp canvas   natural
+11    glass         transparent
+
+Table: Shoes, their sizes, and what they're made of
+
+(The above is the caption for the table.) Pandoc also supports
+multi-line tables:
+
+--------  -----------------------
+keyword   text
+--------  -----------------------
+red       Sunsets, apples, and
+          other red or reddish
+          things.
+
+green     Leaves, grass, frogs
+          and other things it's
+          not easy being.
+--------  -----------------------
+
+A horizontal rule follows.
+
+***
+
+Here's a definition list:
+
+apples
+  : Good for making applesauce.
+oranges
+  : Citrus!
+tomatoes
+  : There's no "e" in tomatoe.
+
+Again, text is indented 4 spaces. (Put a blank line between each
+term/definition pair to spread things out more.)
+
+Here's a "line block":
+
+| Line one
+|   Line too
+| Line tree
+
+and images can be specified like so:
+
+![example image](example-image.jpg "An exemplary image")
+
+Inline math equations go in like so: $\omega = d\phi / dt$. Display
+math should get its own line and be put in in double-dollarsigns:
+
+$$I = \int \rho R^{2} dV$$
+
+And note that you can backslash-escape any punctuation characters
+which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc.

tests/assets/test_text.txt

@@ -0,0 +1 @@
+TEST FILE

tests/helpers.py

@@ -0,0 +1,14 @@
+import os, random, string
+
+
+def clear_env():
+    os.environ.pop("NTFY_USER", None)
+    os.environ.pop("NTFY_PASSWORD", None)
+
+
+def get_topic():
+    return "python_ntfy_testing"
+
+
+def random_string(length=10):
+    return "".join([random.choice(string.ascii_lowercase) for _ in range(length)])