docs: add **extra kwargs guide for job function registration

README.md

@@ -43,7 +43,7 @@ scheduler = PollingScheduler(
     lock_adapter=InMemoryLock(),
 )
 
-def send_email():
+def send_email(**extra):
     print("Sending email...")
 
 scheduler.register_job_function("send_email", send_email)
@@ -61,6 +61,25 @@ scheduler.on(hour=9).config(timezone="Asia/Seoul").run("send_email")
 scheduler.start()
 ```
 
+### Accepting Extra Keyword Arguments
+
+When registering job functions, always declare `**extra` as a catch-all parameter. This ensures your function gracefully handles any additional keyword arguments that may be passed at runtime:
+
+```python
+# Good - accepts extra keyword arguments
+def send_email(**extra):
+    print("Sending email...")
+
+def generate_report(report_type: str, **extra):
+    print(f"Generating {report_type} report...")
+
+# Bad - will raise TypeError on unexpected keyword arguments
+def send_email():
+    print("Sending email...")
+```
+
+This is especially important when your function is called with keyword arguments via `run()` or `kwargs={}`, as future updates or integrations may introduce additional context.
+
 ## API
 
 ```python

examples/dead_letter_queue.py

@@ -139,12 +139,12 @@ def get_statistics(self):
 # =============================================================================
 
 
-def reliable_job():
+def reliable_job(**extra):
     """Job that always succeeds."""
     print(f"[{datetime.now()}] ✅ Reliable job executed successfully")
 
 
-def flaky_job(item_id: int):
+def flaky_job(item_id: int, **extra):
     """Job that fails occasionally."""
     import random
 
@@ -153,7 +153,7 @@ def flaky_job(item_id: int):
     print(f"[{datetime.now()}] ✅ Processed item {item_id}")
 
 
-def always_failing_job(order_id: int):
+def always_failing_job(order_id: int, **extra):
     """Job that always fails (for demonstration)."""
     raise ValueError(f"Payment gateway error for order {order_id}")
 

examples/execution_history.py

@@ -142,19 +142,19 @@ def get_statistics(self, job_id=None):
 # =============================================================================
 
 
-def data_sync_job(source: str):
+def data_sync_job(source: str, **extra):
     """Job that syncs data from source."""
     print(f"[{datetime.now()}] Syncing data from {source}...")
     time.sleep(0.5)
 
 
-def report_generation_job(report_type: str):
+def report_generation_job(report_type: str, **extra):
     """Job that generates reports."""
     print(f"[{datetime.now()}] Generating {report_type} report...")
     time.sleep(0.3)
 
 
-def flaky_api_job():
+def flaky_api_job(**extra):
     """Job that fails occasionally (simulates flaky API)."""
     import random
 

examples/multitenant.py

@@ -5,7 +5,7 @@
 from chronis.adapters.storage import InMemoryStorage
 
 
-def send_report(tenant_name: str):
+def send_report(tenant_name: str, **extra):
     """Send report for a tenant."""
     print(f"Sending report for tenant: {tenant_name}")
 

examples/postgres/postgres_example.py

@@ -26,12 +26,12 @@
 from chronis.contrib.adapters.storage import PostgreSQLStorage
 
 
-def send_notification():
+def send_notification(**extra):
     """Example job function."""
     print(f"[{time.strftime('%H:%M:%S')}] Sending notification...")
 
 
-def generate_report():
+def generate_report(**extra):
     """Another example job function."""
     print(f"[{time.strftime('%H:%M:%S')}] Generating report...")
 

examples/quickstart.py

@@ -10,17 +10,17 @@
 )
 
 
-def send_email():
+def send_email(**extra):
     """Example job function - send email."""
     print(f"[{datetime.now()}] Sending email...")
 
 
-def cleanup_logs():
+def cleanup_logs(**extra):
     """Example job function - cleanup logs."""
     print(f"[{datetime.now()}] Cleaning up logs...")
 
 
-def generate_report(report_type: str):
+def generate_report(report_type: str, **extra):
     """Example job function - generate report."""
     print(f"[{datetime.now()}] Generating {report_type} report...")
 

examples/redis/redis_example.py

@@ -20,12 +20,12 @@
 from chronis.contrib.adapters.storage import RedisStorage
 
 
-def send_email():
+def send_email(**extra):
     """Example job function."""
     print(f"[{time.strftime('%H:%M:%S')}] Sending email...")
 
 
-def process_data():
+def process_data(**extra):
     """Another example job function."""
     print(f"[{time.strftime('%H:%M:%S')}] Processing data...")