python-ntfy 0.5.1__tar.gz → 0.6.0__tar.gz

{python_ntfy-0.5.1 → python_ntfy-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-ntfy
-Version: 0.5.1
+Version: 0.6.0
 Summary: An ntfy library aiming for feature completeness
 License: MIT
 Author: Matthew Cane
@@ -28,11 +28,7 @@ An easy-to-use python library for the [ntfy notification service](https://ntfy.s
 ## 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:
+2. Use the `NtfyClient` to send messages:
 
 ```python
 # Import the ntfy client
@@ -45,6 +41,8 @@ client = NtfyClient(topic="Your topic")
 client.send("Your message here")
 ```
 
+For information on setting up authentication, see the [quickstart guide](https://matthewcane.github.io/python-ntfy/quickstart/).
+
 ## Documentation
 
 See the full documentation at [https://matthewcane.github.io/python-ntfy/](https://matthewcane.github.io/python-ntfy/).
@@ -61,41 +59,28 @@ See the full documentation at [https://matthewcane.github.io/python-ntfy/](https
 - Scheduled delivery
 - Tags
 - Action buttons
+- Email notifications
 
-## Future Features
-
-- [Email notifications](https://docs.ntfy.sh/publish/#e-mail-notifications)
-- Send to multiple topics at once
-
-## Testing and Development
+## Contributing
 
 This project uses:
 
 - [Poetry](https://python-poetry.org/) as it's dependency manager
-- [Ruff](https://docs.astral.sh/ruff/) for linting and code formatting
-- [MyPy](https://mypy-lang.org/) for static type checking
-- [Pre-Commit](https://pre-commit.com/) for running the above tools before committing
-
-To install dev dependencies, run `poetry install --with dev`.
+- [Just](https://github.com/casey/just) as a task runner
+- [Pre-commit](https://pre-commit.com/) for running checks before each commit
+- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) for running tests
 
-To install pre-commit hooks, run `pre-commit install`.
+These need to be installed separately to run the tasks.
 
-### Linting, Formatting and Type Checking
+To see all available tasks, run `just`.
 
-These can be run with:
+Some useful tasks are:
 
-- `poetry run ruff format`
-- `poetry run ruff check`
-- `poetry run mypy .`
-
-These tools are also run in the CI pipeline and must pass before merging.
+- `just install` - Install dependencies (including dev dependencies)
+- `just test` - Run all tests and checks
+- `just serve-docs` - Build and serve the docs locally
 
 ### Tests
 
 This project is aiming for 95% code coverage. Any added features must include comprehensive tests.
 
-#### Testing Steps
-
-1. Make sure you have `docker` and `docker-compose` installed
-2. Run the tests with `poetry run pytest --cov` or use the VSCode testing extension
-

{python_ntfy-0.5.1 → python_ntfy-0.6.0}/README.md

@@ -9,11 +9,7 @@ An easy-to-use python library for the [ntfy notification service](https://ntfy.s
 ## 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:
+2. Use the `NtfyClient` to send messages:
 
 ```python
 # Import the ntfy client
@@ -26,6 +22,8 @@ client = NtfyClient(topic="Your topic")
 client.send("Your message here")
 ```
 
+For information on setting up authentication, see the [quickstart guide](https://matthewcane.github.io/python-ntfy/quickstart/).
+
 ## Documentation
 
 See the full documentation at [https://matthewcane.github.io/python-ntfy/](https://matthewcane.github.io/python-ntfy/).
@@ -42,40 +40,27 @@ See the full documentation at [https://matthewcane.github.io/python-ntfy/](https
 - Scheduled delivery
 - Tags
 - Action buttons
+- Email notifications
 
-## Future Features
-
-- [Email notifications](https://docs.ntfy.sh/publish/#e-mail-notifications)
-- Send to multiple topics at once
-
-## Testing and Development
+## Contributing
 
 This project uses:
 
 - [Poetry](https://python-poetry.org/) as it's dependency manager
-- [Ruff](https://docs.astral.sh/ruff/) for linting and code formatting
-- [MyPy](https://mypy-lang.org/) for static type checking
-- [Pre-Commit](https://pre-commit.com/) for running the above tools before committing
-
-To install dev dependencies, run `poetry install --with dev`.
+- [Just](https://github.com/casey/just) as a task runner
+- [Pre-commit](https://pre-commit.com/) for running checks before each commit
+- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) for running tests
 
-To install pre-commit hooks, run `pre-commit install`.
+These need to be installed separately to run the tasks.
 
-### Linting, Formatting and Type Checking
+To see all available tasks, run `just`.
 
-These can be run with:
+Some useful tasks are:
 
-- `poetry run ruff format`
-- `poetry run ruff check`
-- `poetry run mypy .`
-
-These tools are also run in the CI pipeline and must pass before merging.
+- `just install` - Install dependencies (including dev dependencies)
+- `just test` - Run all tests and checks
+- `just serve-docs` - Build and serve the docs locally
 
 ### Tests
 
 This project is aiming for 95% code coverage. Any added features must include comprehensive tests.
-
-#### Testing Steps
-
-1. Make sure you have `docker` and `docker-compose` installed
-2. Run the tests with `poetry run pytest --cov` or use the VSCode testing extension

{python_ntfy-0.5.1 → python_ntfy-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-ntfy"
-version = "0.5.1"
+version = "0.6.0"
 description = "An ntfy library aiming for feature completeness"
 authors = ["Matthew Cane <matthew.cane0@gmail.com>"]
 readme = "README.md"
@@ -24,7 +24,7 @@ mkdocstrings = {extras = ["python"], version = ">=0.26.2,<0.30.0"}
 mypy = "^1.12.0"
 pytest = ">=7.4.1,<9.0.0"
 python-dotenv = "^1.0.0"
-pytest-asyncio = ">=0.21.1,<1.1.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"
@@ -33,7 +33,6 @@ 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"
-black = ">=24.10,<26.0"
 
 [build-system]
 requires = ["poetry-core"]

{python_ntfy-0.5.1 → python_ntfy-0.6.0}/python_ntfy/_ntfy.py

@@ -46,12 +46,14 @@ class NtfyClient(GetFunctionsMixin, SendFunctionsMixin):
         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
@@ -65,18 +67,39 @@ class NtfyClient(GetFunctionsMixin, SendFunctionsMixin):
         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)
 
-        # If the user has set the user and password, use that
-        # If the user has set the token, use that
-        # Otherwise, use None
-
-        self._auth: tuple[str, str] | None = None
-        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)
+    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,

{python_ntfy-0.5.1 → python_ntfy-0.6.0}/python_ntfy/_send_functions.py

@@ -192,6 +192,7 @@ def send(
     schedule: Optional[datetime] = None,
     format_as_markdown: bool = False,
     timeout_seconds: int = 5,
+    email: Optional[str] = None,
 ) -> dict:
     """Send a text-based message to the server.
 
@@ -208,6 +209,7 @@ def send(
         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 the reqest to the server.
+        email: Forward messages to an email address. Only one email address can be specified.
 
     Returns:
         dict: The response from the server.
@@ -236,6 +238,9 @@ def send(
     if len(actions) > 0:
         headers["Actions"] = " ; ".join([action.to_header() for action in actions])
 
+    if email:
+        headers["Email"] = email
+
     if schedule:
         headers["Delay"] = str(int(schedule.timestamp()))
 
@@ -259,6 +264,7 @@ def send_file(
     actions: Optional[list[Union[ViewAction, BroadcastAction, HttpAction]]] = None,
     schedule: Optional[datetime] = None,
     timeout_seconds: int = 30,
+    email: Optional[str] = None,
 ) -> dict:
     """Sends a file to the server.
 
@@ -270,6 +276,7 @@ def send_file(
         actions: A list of ActionButton objects to attach to the message.
         schedule: The time to schedule the message to be sent. Must be more than 10 seconds away and less than 3 days in the future.
         timeout_seconds: The number of seconds to wait before timing out.
+        email: Forward messages to an email address. Only one email address can be specified.
 
     Returns:
         dict: The response from the server.
@@ -293,6 +300,9 @@ def send_file(
         "Actions": " ; ".join([action.to_header() for action in actions]),
     }
 
+    if email:
+        headers["Email"] = email
+
     if schedule:
         headers["Delay"] = str(int(schedule.timestamp()))