Merge pull request #9 from ms7m/dev

v0.2.2

.gitignore

@@ -2,6 +2,7 @@
 
 .vscode/*
 test.py
+build.sh
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

MANIFEST.in

@@ -1,2 +1,3 @@
 include notifypy/py-logo.png
+include notifypy/example_notification_sound.wav
 recursive-include notifypy/os_notifiers/binaries *

README.md

@@ -18,6 +18,10 @@
 </div>
 
 
+## Docs
+
+[Read the Docs here](https://ms7m.github.io/notify-py/)
+
 ## Supported Platforms.
 
 - Windows 10

docs/docs/custom_mac_notifications.md

@@ -0,0 +1,88 @@
+# Custom Icons for macOS		
+
+Due to restrictions set by macOS, there isn't a way to add a custom icon on the fly. You'll need to create a customized version of the notifier used. 
+
+***
+
+**Clone the notificator repo**
+
+```
+git clone https://github.com/vitorgalvao/notificator
+```
+
+Follow the instructions in the README.md for adding a custom icon. It will spit out an ``.app``.  You'll need it for later.
+
+***
+
+You now have two options. 
+
+- You can either build a custom wheel from this repository. This will include your custom notificator.
+- You can provide a path to the custom notificator, and tell notify.py to use that one instead of the bundled version.
+
+***
+
+
+
+## Option 1
+
+**Clone the notify.py repo.**
+
+```
+git clone https://github.com/ms7m/notify-py
+```
+
+
+**Create your virtual environment**
+
+```
+python -m venv venv
+```
+
+**Install the dependencies to build**
+
+```
+python3 -m pip install loguru
+python3 -m pip install --user --upgrade setuptools wheel
+```
+
+After that's done, copy the .app into ``notifypy/os_notifiers/binary`` folder. 
+
+Make sure the executable inside ``/os_notifiers/binary/Notificator.app/Contents/Resources/Scripts/notificator``has the needed permissions to execute. 
+
+**Test before building**
+
+```python
+import notifypy
+n = notifypy.Notify()
+n.send()
+```
+
+You can also run the tests inside the ``tests/`` folder. (Install pytest before)
+
+**If everything works out, go ahead and build the wheel.**
+
+```
+python3 setup.py sdist bdist_wheel
+```
+
+You'll be supplied with a .whl inside the ``dist/`` folder. 
+
+*How you distribute this wheel is up to you.  It's probably best to add it to a git repo, and add it to your requirements.txt file.*
+
+***
+
+
+
+## Option 2
+
+If you prefer, you can also forward a path to your custom notificator to notify.py by using the optional kwarg ``custom_mac_notificator``.
+
+```python
+import notifypy
+
+n = notifypy.Notify(
+	custom_mac_notificator="path/to/custom.app"
+)
+```
+
+Make sure that the notificator is executable. 

docs/docs/custom_notifications.md

@@ -0,0 +1,35 @@
+# Custom Notifications
+
+Custom notifications can be made if you choose.
+
+```python
+from notifypy import BaseNotifier
+from notifypy import Notify
+
+
+class CustomNotifier(BaseNotifier):
+    def __init__(self, **kwargs):
+        pass
+
+    def send_notification(self, **kwargs):
+        print("Yes. This works.")
+        return True
+
+
+n = Notify(
+    override_detected_notification_system=CustomNotifier,
+    # This can be anything for the key.
+    custom_notification_arguments="Bob",
+)
+
+n.send()
+```
+
+
+
+They must
+
+- Inherit ``BaseNotifier``
+- Expose ``send_notification``.
+
+If you wish to have custom arguments, you can do add ``kwargs`` and notify.py will forward them.

docs/docs/index.md

@@ -0,0 +1,48 @@
+# Documentation for Notify.py
+
+<div align="center">
+  <p align="center">
+    <img src="https://github.com/ms7m/notify-py/workflows/Test%20Linux/badge.svg">
+    <img src="https://github.com/ms7m/notify-py/workflows/Test%20macOS/badge.svg">
+    <img src="https://github.com/ms7m/notify-py/workflows/Test%20Windows/badge.svg">
+  </p>
+  <br>
+  <p align="center">
+    <img src="https://img.shields.io/badge/Available-on%20PyPi-blue?logoColor=white&logo=Python">
+    <img src="https://img.shields.io/badge/Python-3.6%2B-blue?logo=python">
+    <img src="https://img.shields.io/badge/Formatting-Black-black.svg">
+  </p>
+</div>
+
+
+## Notify.py
+
+notify.py is a small python module for sending native cross-platform notifications. The only dependency required is loguru.
+
+***
+
+
+
+## Getting started
+
+```python
+from notifypy import Notify
+
+notification = Notify()
+notification.title = "Cool Title"
+notification.message = "Even cooler message."
+
+notification.send()
+```
+
+That's it. This will send a desktop notification on the respected user platform.
+
+***
+
+# Installation 
+
+```python
+pip install notify-py
+```
+
+***

docs/docs/optional_arguments.md

@@ -0,0 +1,26 @@
+# Optional Arguments
+
+
+
+Intended for the ``notifypy.Notify`` object.
+
+***
+
+
+
+### ``override_detected_notification_system``
+
+- Any object that inherits from ``BaseNotifier``.
+
+
+
+### ``enable_logging``
+
+- Enables stdout logging from this library.
+
+
+
+### ``custom_mac_notificator``
+
+- Optional argument to point to a system path to a custom macOS notificator.
+

docs/docs/sending_notifications.md

@@ -0,0 +1,100 @@
+
+
+
+
+# Sending Notifications.
+
+
+
+## ⚠️ Important Caveats
+
+As it stands (May 18, 2020), this is simply a notification service. There is **no** support for embedding custom actions (buttons, dialogs) regardless of platform. Other then telling you if the shell command was sent, there is also no confirmation on user action on the notification. 
+
+
+
+macOS does ***\*not\**** support custom icons on the fly.. You will need to bundle a customized version of the notifier embedded with your custom icon. 
+
+***
+
+
+
+## Sending Notifications with a Custom Icon
+
+> Caution: **macOS** does not support custom icons on the fly. You'll need to generate customized binary and point notify-py to it. 
+
+
+
+```python
+from notifypy import Notify
+
+notification = Notify()
+notification.title = "Cool Title"
+notification.message = "Even cooler message."
+notification.icon = "path/to/icon.png"
+
+notification.send()
+
+```
+
+.pngs were tested on all platforms. Windows might require a smaller version of your .png. 
+
+
+
+***
+
+## Sending Notifications with a Custom Sound
+
+> Caution: Be wary, this will be play a sound fully. Please be responsible.
+
+```python
+from notifypy import Notify
+
+notification = Notify()
+notification.title = "Cool Title"
+notification.message = "Even cooler message."
+notification.audio = "path/to/audio/file.wav"
+
+notification.send()
+
+```
+
+
+
+***
+
+## Sending Notifications without blocking.
+
+By default, execution of your script might stop when sending the notifications. While it's not crazy limited (often >1sec). You might want to make sure that all notification sending happens outside the scope of the app. 
+
+```python
+from notifypy import Notify
+
+notification = Notify()
+notification.send(block=False)
+
+```
+
+This spawns a separate thread for creating and sending the notification.
+
+***
+
+## Sending with a Default Notification Title/Message/Icon/Sound
+
+```python
+
+from notifypy import Notify
+
+notification = Notify(
+  default_notification_title="Function Message",
+  default_application_name="Great Application",
+  default_notification_icon="path/to/icon.png",
+  default_notification_audio="path/to/sound.wav"
+)
+
+def your_function():
+  # stuff happening here.
+  notification.message = "Function Result"
+  notification.send()
+```
+
+

docs/mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: notify-py
+nav:
+    - Home: index.md
+    - Sending Notifications: sending_notifications.md
+    - Creating Custom Notifications: custom_notifications.md
+    - Custom macOS notification icons: custom_mac_notifications.md
+    - Optional Arguments: optional_arguments.md
+theme: readthedocs