android-notify 1.61.3.dev0__tar.gz → 1.61.5__tar.gz

{android_notify-1.61.3.dev0 → android_notify-1.61.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: android-notify
-Version: 1.61.3.dev0
+Version: 1.61.5
 Summary: A Python package that simplifies creating Android notifications in Kivy and Flet apps.
 Author-email: Fabian <fector101@yahoo.com>
 License-Expression: MIT
@@ -16,7 +16,6 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Description-Content-Type: text/markdown
-Requires-Dist: pyjnius
 Provides-Extra: dev
 Requires-Dist: kivy; extra == "dev"
 
@@ -28,6 +27,9 @@ Requires-Dist: kivy; extra == "dev"
     <!-- <br> -->
     <!-- <img src="https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/democollage.jpg"> -->
 </div>
+
+[![PyPI](https://badge.fury.io/py/android-notify.svg)](https://badge.fury.io/py/android-notify)
+
 <!-- Channel [CRUD]
 The Android Notify package provides a simple yet comprehensive way to create and manage rich notifications on Android devices directly from your Python code. This library bridges the gap between Python and Android's notification system, giving you full control over notifications with a clean, Pythonic API. -->
 
@@ -45,7 +47,7 @@ The Android Notify package provides a simple yet comprehensive way to create and
   - Colored texts and Icons
 
 - **Rich Functionality**:
-  - Add action buttons with custom callbacks
+  - Add action Buttons with custom callbacks - [Buttons section](https://android-notify.vercel.app/components#buttons)
   - [Update notification](https://android-notify.vercel.app/advanced-methods#updating-notification) content dynamically
   - Manage progress bars with fine-grained control
   - [Custom notification channels](https://android-notify.vercel.app/advanced-methods#channel-management) for Android 8.0+ (Creating and Deleting)
@@ -53,6 +55,8 @@ The Android Notify package provides a simple yet comprehensive way to create and
   - Persistent notifications
   - Click handlers and callbacks
   - Cancel Notifications
+  - Use [Custom Sound](https://android-notify.vercel.app/advanced-methods#custom-sound)
+  - Vibration [section](https://android-notify.vercel.app/advanced-methods#vibration)
 
 ## Quick Start
 
@@ -79,15 +83,14 @@ Notification(
 In your **`buildozer.spec`** file, ensure you include the following:
 
 ```ini
-# Add pyjnius so ensure it's packaged with the build
-requirements = python3, kivy, pyjnius, android-notify==1.61.3.dev0
+# Add requirements list
+requirements = python3, kivy, pyjnius, android-notify
 # Add permission for notifications
 android.permissions = POST_NOTIFICATIONS
 ```
 
 </details>
 
-
 <details>
 <summary><b>Flet apps:</b></summary>
 <br/>
@@ -98,7 +101,7 @@ In your `pyproject.toml` file, ensure you include the following:
 ```toml
 [tool.flet.android]
 dependencies = [
-  "pyjnius","android-notify==1.61.3.dev0"
+  "pyjnius", "android-notify"
 ]
 
 [tool.flet.android.permission]
@@ -108,23 +111,19 @@ dependencies = [
 
 </details>
 
-
-
 <details>
 
 <summary><b>On Pydroid 3</b></summary>
 <br/>
 
 On the [pydroid 3](https://play.google.com/store/apps/details?id=ru.iiec.pydroid3) mobile app for running python code you can test some features.
-- In pip section where you're asked to insert `Libary name` paste `android-notify==1.61.3.dev0`
+- In pip section where you're asked to insert `Libary name` paste `android-notify`
 - Minimal working example 
 ```py
-# Testing with `android-notify==1.61.3.dev0` on pydroid
 from kivy.app import App
 from kivy.uix.boxlayout import BoxLayout
 from kivy.uix.button import Button
-from android_notify import Notification
-from android_notify.core import asks_permission_if_needed
+from android_notify import Notification, NotificationHandler
 
 
 class AndroidNotifyDemoApp(App):
@@ -141,14 +140,12 @@ class AndroidNotifyDemoApp(App):
         return layout
 
     def request_permission(self, *args):
-        asks_permission_if_needed(legacy=True)
+        NotificationHandler.asks_permission()
 
     def send_notification(self, *args):
         Notification(
             title="Hello from Android Notify",
-            message="This is a basic notification.",
-            channel_id="android_notify_demo",
-            channel_name="Android Notify Demo"
+            message="This is a basic notification."
         ).send()
 
 
@@ -172,38 +169,116 @@ android-notify -v
 ```
 </details>
 
-## Documentation
-For Dev Version use
-```ini
-requirements = python3, kivy, pyjnius, https://github.com/Fector101/android_notify/archive/without-androidx.zip
+## Common Methods
+For full visit [documentation](https://android-notify.vercel.app) for more examples and advanced usage.
+### For Images
+Source can be local file paths or complete URLs execpt `setSmallIcon` which only accepts local `png` files.
+
+- `setBigPicture` - shows below when user clicks drop button
+- `setLargeIcon` - appears at right side of notification content
+- `setSmallIcon` - changes app icon to a custom `png`
+- `setColor` - changes app icon backgroud Color
+
+For online images URL should with `https://` and you need internet permission `android.permissions = INTERNET` in `buildozer.spec` or `pyproject.toml`
+
+```python
+from android_notify import Notification
+
+notification = Notification(
+    title='Picture Alert!',
+    message='This notification uses setLargelcon and setBig Picture method.'
+)
+notification.setBigPicture("imgs/photo.png")
+notification.setLargeIcon("imgs/profile.png")
+notification.send()
 ```
 
-<details>
-<summary> <b> To talk to BroadCast Listener From Buttons </b> </summary>
+**Sample Image:**  
+![basic notification img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/images-methods.jpg)
 
-- Make things happen without being in your app
 ```python
 from android_notify import Notification
-notification = Notification(title="Receiver Notification")
-notification.addButton(text="Stop", receiver_name="CarouselReceiver", action="ACTION_STOP")
-notification.addButton(text="Skip", receiver_name="CarouselReceiver", action="ACTION_SKIP")
+
+notification = Notification(
+    title='Custom Icon and Color',
+    message='This notification uses setColor and setSmallIcon.'
+)
+notification.setColor("red")
+notification.setSmallIcon("love.png")
+notification.send()
 ```
-You can use this [wiki](https://github.com/Fector101/android_notify/wiki/How-to-Use-with-Broadcast-Listener) as a guide create a broadcast listener
-</details>
 
-<details>
-<summary> <b> To use colored text in your notifications </b> </summary>
+**Sample Image:**  
+![basic notification img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/images-methods1.jpg)
+
 
-- Copy the [res](https://github.com/Fector101/android_notify/tree/main/android_notify/res) folder to your app path.  
-- Lastly in your `buildozer.spec` file  
-Add `source.include_exts = xml` and `android.add_resources = # path you pasted`
+### For ProgressBar
+
+- `updateProgressBar(current_value, message, title)` - update progress in real-time
+- `showInfiniteProgressBar` - shows an infinite progress animation.
+- `removeProgressBar(message, show_on_update=True, title)` - Cleanly remove the progress bar.
 ```python
-# Use Hex Code to be Safe
-n = Notification(title="Title and Message Color", message="Testing",title_color="red")
-n.send()
+from android_notify import Notification
+from kivy.clock import Clock
+
+progress = 0
+
+notification = Notification(
+    title="Downloading...", message="0% downloaded",
+    progress_current_value=0, progress_max_value=100
+)
+notification.send()
+
+def update_progress(dt):
+    global progress
+    progress = min(progress + 10, 100)
+    
+    if progress==100:
+        notification.removeProgressBar(title="File Downloaded", message="super_large_file.zip")
+    elif progress >= 80:
+        notification.showInfiniteProgressBar()
+    else:
+        notification.updateProgressBar(progress, f"{progress}% downloaded")
+
+    return progress < 100  # Ends loop when reaching 100%
+
+Clock.schedule_interval(update_progress, 3)
 ```
+![progressbar img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/progressbar.gif)
 
-</details>
+
+### For texts
+- `addLine` - adds a line to the notification, useful for inbox style
+- `setSubText` - sets a smaller text that appears at the side of app name
+- `setBigText` - sets a longer text that appears when the notification is expanded
+- `updateTitle` - updates the title text of the notification
+- `updateMessage` - updates the main message text of the notification
+```python
+from android_notify import Notification
+
+notification = Notification(
+    title="5 New mails from Frank",
+    message="Check them out",
+)
+notification.setSubText("FabianCodes")
+notification.setLargeIcon("imgs/profile.png")
+notification.addLine("Re: Planning")
+notification.addLine("Delivery on its way")
+notification.addLine("Follow-up")
+notification.send()
+```
+![inbox-subtext img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/inbox-subtext.jpg)
+
+## Documentation
+### For full documentation, examples, and advanced usage, API reference visit the [documentation](https://android-notify.vercel.app)
+---
+
+For Dev Version usage
+```ini
+requirements = python3, kivy, pyjnius, https://github.com/Fector101/android_notify/archive/main.zip
+```
+
+### Dev Features docs
 
 <details>
 <summary> <b>To use Custom Sounds </b> </summary>
@@ -267,26 +342,6 @@ Private files (e.g., in app's `data/` directory) are automatically copied to ext
 </details>
 
 
-<details>
-<summary> <b> Vibrate feature</b> </summary>
-
-```ini
-# buildozer.spec
-android.permissions = VIBRATE
-```
-
-```python
-Notification.createChannel(id='shake', name="Shake Passage", vibrate=True)
-
-n=Notification(title='Vibrate',channel_id='shake')
-n.setVibrate() # for less than android 8
-n.fVibrate() # To Force Vibrate (when user turned off in settings)
-n.send()
-```
-
-</details>
-
-
 <details>
 <summary> <b> Add Data to Notification</b> </summary>
 
@@ -314,7 +369,31 @@ from android_notify import Notification, NotificationHandler
 </details>
 
 
-### For full documentation, examples, and advanced usage, API reference visit the [documentation](https://android-notify.vercel.app)
+<details>
+<summary> <b>How to control popups</b> </summary>
+    
+```python
+from android_notify import Notification
+import time
+
+notification = Notification(
+    title="Processing...",
+    message="Starting task"
+)
+
+notification.send()
+time.sleep(10)
+
+# show heads-up when updated
+notification.setOnlyAlertOnce(False)
+
+notification.updateTitle("Processing Complete!")
+notification.updateMessage("Task finished successfully")
+```
+
+</details>
+
+
 
 ## ☕ Support the Project
 
@@ -324,3 +403,16 @@ Or Giving it a star on 🌟 [GitHub](https://github.com/Fector101/android_notify
 <a href="https://www.buymeacoffee.com/fector101" target="_blank">
   <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60">
 </a>
+
+## Bug Reports & Feature Requests
+
+Found a bug or have an idea for a new feature?  
+Feel free to open an issue [here](https://github.com/Fector101/android_notify/issues)
+
+When reporting a bug, try to include:
+- Device name
+- Android version
+- Steps to reproduce the issue
+- Screenshots or logs (if possible)
+
+Feature suggestions are also welcome.

{android_notify-1.61.3.dev0 → android_notify-1.61.5}/README.md

@@ -6,6 +6,9 @@
     <!-- <br> -->
     <!-- <img src="https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/democollage.jpg"> -->
 </div>
+
+[![PyPI](https://badge.fury.io/py/android-notify.svg)](https://badge.fury.io/py/android-notify)
+
 <!-- Channel [CRUD]
 The Android Notify package provides a simple yet comprehensive way to create and manage rich notifications on Android devices directly from your Python code. This library bridges the gap between Python and Android's notification system, giving you full control over notifications with a clean, Pythonic API. -->
 
@@ -23,7 +26,7 @@ The Android Notify package provides a simple yet comprehensive way to create and
   - Colored texts and Icons
 
 - **Rich Functionality**:
-  - Add action buttons with custom callbacks
+  - Add action Buttons with custom callbacks - [Buttons section](https://android-notify.vercel.app/components#buttons)
   - [Update notification](https://android-notify.vercel.app/advanced-methods#updating-notification) content dynamically
   - Manage progress bars with fine-grained control
   - [Custom notification channels](https://android-notify.vercel.app/advanced-methods#channel-management) for Android 8.0+ (Creating and Deleting)
@@ -31,6 +34,8 @@ The Android Notify package provides a simple yet comprehensive way to create and
   - Persistent notifications
   - Click handlers and callbacks
   - Cancel Notifications
+  - Use [Custom Sound](https://android-notify.vercel.app/advanced-methods#custom-sound)
+  - Vibration [section](https://android-notify.vercel.app/advanced-methods#vibration)
 
 ## Quick Start
 
@@ -57,15 +62,14 @@ Notification(
 In your **`buildozer.spec`** file, ensure you include the following:
 
 ```ini
-# Add pyjnius so ensure it's packaged with the build
-requirements = python3, kivy, pyjnius, android-notify==1.61.3.dev0
+# Add requirements list
+requirements = python3, kivy, pyjnius, android-notify
 # Add permission for notifications
 android.permissions = POST_NOTIFICATIONS
 ```
 
 </details>
 
-
 <details>
 <summary><b>Flet apps:</b></summary>
 <br/>
@@ -76,7 +80,7 @@ In your `pyproject.toml` file, ensure you include the following:
 ```toml
 [tool.flet.android]
 dependencies = [
-  "pyjnius","android-notify==1.61.3.dev0"
+  "pyjnius", "android-notify"
 ]
 
 [tool.flet.android.permission]
@@ -86,23 +90,19 @@ dependencies = [
 
 </details>
 
-
-
 <details>
 
 <summary><b>On Pydroid 3</b></summary>
 <br/>
 
 On the [pydroid 3](https://play.google.com/store/apps/details?id=ru.iiec.pydroid3) mobile app for running python code you can test some features.
-- In pip section where you're asked to insert `Libary name` paste `android-notify==1.61.3.dev0`
+- In pip section where you're asked to insert `Libary name` paste `android-notify`
 - Minimal working example 
 ```py
-# Testing with `android-notify==1.61.3.dev0` on pydroid
 from kivy.app import App
 from kivy.uix.boxlayout import BoxLayout
 from kivy.uix.button import Button
-from android_notify import Notification
-from android_notify.core import asks_permission_if_needed
+from android_notify import Notification, NotificationHandler
 
 
 class AndroidNotifyDemoApp(App):
@@ -119,14 +119,12 @@ class AndroidNotifyDemoApp(App):
         return layout
 
     def request_permission(self, *args):
-        asks_permission_if_needed(legacy=True)
+        NotificationHandler.asks_permission()
 
     def send_notification(self, *args):
         Notification(
             title="Hello from Android Notify",
-            message="This is a basic notification.",
-            channel_id="android_notify_demo",
-            channel_name="Android Notify Demo"
+            message="This is a basic notification."
         ).send()
 
 
@@ -150,38 +148,116 @@ android-notify -v
 ```
 </details>
 
-## Documentation
-For Dev Version use
-```ini
-requirements = python3, kivy, pyjnius, https://github.com/Fector101/android_notify/archive/without-androidx.zip
+## Common Methods
+For full visit [documentation](https://android-notify.vercel.app) for more examples and advanced usage.
+### For Images
+Source can be local file paths or complete URLs execpt `setSmallIcon` which only accepts local `png` files.
+
+- `setBigPicture` - shows below when user clicks drop button
+- `setLargeIcon` - appears at right side of notification content
+- `setSmallIcon` - changes app icon to a custom `png`
+- `setColor` - changes app icon backgroud Color
+
+For online images URL should with `https://` and you need internet permission `android.permissions = INTERNET` in `buildozer.spec` or `pyproject.toml`
+
+```python
+from android_notify import Notification
+
+notification = Notification(
+    title='Picture Alert!',
+    message='This notification uses setLargelcon and setBig Picture method.'
+)
+notification.setBigPicture("imgs/photo.png")
+notification.setLargeIcon("imgs/profile.png")
+notification.send()
 ```
 
-<details>
-<summary> <b> To talk to BroadCast Listener From Buttons </b> </summary>
+**Sample Image:**  
+![basic notification img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/images-methods.jpg)
 
-- Make things happen without being in your app
 ```python
 from android_notify import Notification
-notification = Notification(title="Receiver Notification")
-notification.addButton(text="Stop", receiver_name="CarouselReceiver", action="ACTION_STOP")
-notification.addButton(text="Skip", receiver_name="CarouselReceiver", action="ACTION_SKIP")
+
+notification = Notification(
+    title='Custom Icon and Color',
+    message='This notification uses setColor and setSmallIcon.'
+)
+notification.setColor("red")
+notification.setSmallIcon("love.png")
+notification.send()
 ```
-You can use this [wiki](https://github.com/Fector101/android_notify/wiki/How-to-Use-with-Broadcast-Listener) as a guide create a broadcast listener
-</details>
 
-<details>
-<summary> <b> To use colored text in your notifications </b> </summary>
+**Sample Image:**  
+![basic notification img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/images-methods1.jpg)
+
 
-- Copy the [res](https://github.com/Fector101/android_notify/tree/main/android_notify/res) folder to your app path.  
-- Lastly in your `buildozer.spec` file  
-Add `source.include_exts = xml` and `android.add_resources = # path you pasted`
+### For ProgressBar
+
+- `updateProgressBar(current_value, message, title)` - update progress in real-time
+- `showInfiniteProgressBar` - shows an infinite progress animation.
+- `removeProgressBar(message, show_on_update=True, title)` - Cleanly remove the progress bar.
 ```python
-# Use Hex Code to be Safe
-n = Notification(title="Title and Message Color", message="Testing",title_color="red")
-n.send()
+from android_notify import Notification
+from kivy.clock import Clock
+
+progress = 0
+
+notification = Notification(
+    title="Downloading...", message="0% downloaded",
+    progress_current_value=0, progress_max_value=100
+)
+notification.send()
+
+def update_progress(dt):
+    global progress
+    progress = min(progress + 10, 100)
+    
+    if progress==100:
+        notification.removeProgressBar(title="File Downloaded", message="super_large_file.zip")
+    elif progress >= 80:
+        notification.showInfiniteProgressBar()
+    else:
+        notification.updateProgressBar(progress, f"{progress}% downloaded")
+
+    return progress < 100  # Ends loop when reaching 100%
+
+Clock.schedule_interval(update_progress, 3)
 ```
+![progressbar img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/progressbar.gif)
 
-</details>
+
+### For texts
+- `addLine` - adds a line to the notification, useful for inbox style
+- `setSubText` - sets a smaller text that appears at the side of app name
+- `setBigText` - sets a longer text that appears when the notification is expanded
+- `updateTitle` - updates the title text of the notification
+- `updateMessage` - updates the main message text of the notification
+```python
+from android_notify import Notification
+
+notification = Notification(
+    title="5 New mails from Frank",
+    message="Check them out",
+)
+notification.setSubText("FabianCodes")
+notification.setLargeIcon("imgs/profile.png")
+notification.addLine("Re: Planning")
+notification.addLine("Delivery on its way")
+notification.addLine("Follow-up")
+notification.send()
+```
+![inbox-subtext img sample](https://raw.githubusercontent.com/Fector101/android_notify/main/docs/imgs/inbox-subtext.jpg)
+
+## Documentation
+### For full documentation, examples, and advanced usage, API reference visit the [documentation](https://android-notify.vercel.app)
+---
+
+For Dev Version usage
+```ini
+requirements = python3, kivy, pyjnius, https://github.com/Fector101/android_notify/archive/main.zip
+```
+
+### Dev Features docs
 
 <details>
 <summary> <b>To use Custom Sounds </b> </summary>
@@ -245,26 +321,6 @@ Private files (e.g., in app's `data/` directory) are automatically copied to ext
 </details>
 
 
-<details>
-<summary> <b> Vibrate feature</b> </summary>
-
-```ini
-# buildozer.spec
-android.permissions = VIBRATE
-```
-
-```python
-Notification.createChannel(id='shake', name="Shake Passage", vibrate=True)
-
-n=Notification(title='Vibrate',channel_id='shake')
-n.setVibrate() # for less than android 8
-n.fVibrate() # To Force Vibrate (when user turned off in settings)
-n.send()
-```
-
-</details>
-
-
 <details>
 <summary> <b> Add Data to Notification</b> </summary>
 
@@ -292,7 +348,31 @@ from android_notify import Notification, NotificationHandler
 </details>
 
 
-### For full documentation, examples, and advanced usage, API reference visit the [documentation](https://android-notify.vercel.app)
+<details>
+<summary> <b>How to control popups</b> </summary>
+    
+```python
+from android_notify import Notification
+import time
+
+notification = Notification(
+    title="Processing...",
+    message="Starting task"
+)
+
+notification.send()
+time.sleep(10)
+
+# show heads-up when updated
+notification.setOnlyAlertOnce(False)
+
+notification.updateTitle("Processing Complete!")
+notification.updateMessage("Task finished successfully")
+```
+
+</details>
+
+
 
 ## ☕ Support the Project
 
@@ -302,3 +382,16 @@ Or Giving it a star on 🌟 [GitHub](https://github.com/Fector101/android_notify
 <a href="https://www.buymeacoffee.com/fector101" target="_blank">
   <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60">
 </a>
+
+## Bug Reports & Feature Requests
+
+Found a bug or have an idea for a new feature?  
+Feel free to open an issue [here](https://github.com/Fector101/android_notify/issues)
+
+When reporting a bug, try to include:
+- Device name
+- Android version
+- Steps to reproduce the issue
+- Screenshots or logs (if possible)
+
+Feature suggestions are also welcome.