From 14ddf9aa9691d584a4155508ff4d5420b0f4d159 Mon Sep 17 00:00:00 2001
From: Pedro Rodrigues <medecau@gmail.com>
Date: Wed, 13 Mar 2024 21:39:57 +0100
Subject: [PATCH] Update README to include the new  decorator

---
 README.md | 47 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 31806a4..f0b3f0a 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@ The `sched2` module extends the general purpose event scheduler `sched` from Pyt
 
 # Install
 
-To install the `sched2` module, you can use `pip`, the package installer for Python. Open a terminal and run the following command:
+`sched2` is available on PyPI.
 
 ```bash
 pip install sched2
@@ -11,50 +11,67 @@ pip install sched2
 # Examples
 
 The code below uses the `every` decorator to schedule checking the public IP address every two minutes.
+Then every day at 9:00, the `cron` decorator is used to send a report via email.
+Finally, the `on` decorator is used to send an email when the IP address changes.
+
 
 ```python
+from smtplib import SMTP_SSL
 from urllib.request import urlopen
+
 from sched2 import scheduler
 
 # Create a scheduler
 sc = scheduler()
 
+# we'll use this to remember the last IP address between runs
+last_ip = None
 
-@sc.every(120)  # Run every two minutes
+
+@sc.every(30)  # Run every two minutes
 def print_ip_address():
+    global last_ip
+
     ip = urlopen("https://icanhazip.com/").read().decode("utf-8").strip()
+
     print(f"Public IP address: {ip}")
 
-# Run the scheduler
-sc.run()
-```
+    last_ip = last_ip or ip  # reset last_ip
+    if ip != last_ip:
+        last_ip = ip
 
+        # Emit an event when the IP address changes
+        sc.emit("ip_changed", kwargs={"new_ip": ip})
 
-The following code does something similar, but here we use the `cron` decorator to schedule an email report to be sent every weekday at 9:00.
 
-```python
-from smtplib import SMTP_SSL
-from sched2 import scheduler
+@sc.cron("0 9 * * 1-5")  # Run every weekday at 9:00
+def send_report():
+    sendmail("Daily Report", "The numbers are up!")
 
-# Create a scheduler
-sc = scheduler()
 
+@sc.on("ip_changed")  # Run when 'ip_changed' event is emitted
+def send_email(new_ip):
+    sendmail("IP Address Changed", f"New IP address: {ip}")
 
-@sc.cron("0 9 * * 1-5")  # Run every weekday at 9:00
-def send_report():
+
+def sendmail(subject, body):
+    """Send an email using SMTP_SSL."""
     with SMTP_SSL("smtp.example.com") as smtp:
         smtp.login("me@example.com", "password")
         smtp.sendmail(
             "me@example.com",
             "team@example.com",
-            "Subject: Daily Report\n\nThe numbers are up!",
+            f"{subject}\n\n{body}",
         )
 
 
 # Run the scheduler
 sc.run()
+
 ```
 
 # Source Code and Issues
 
-Help improve sched2 by reporting any issues or suggestions on the issue tracker at [github.com/medecau/sched2/issues](https://github.com/medecau/sched2/issues).
+The source code for `sched2` is available on GitHub at [github.com/medecau/sched2](https://github.com/medecau/sched2).
+
+You can help improve sched2 by reporting any issues or suggestions on the issue tracker at [github.com/medecau/sched2/issues](https://github.com/medecau/sched2/issues).