cherrypy-foundation 1.0.0a1__py3-none-any.whl → 1.0.0a3__py3-none-any.whl

cherrypy_foundation/plugins/scheduler.py

@@ -1,5 +1,5 @@
 # Scheduler plugins for Cherrypy
-# Copyright (C) 2022-2025 IKUS Software
+# Copyright (C) 2025 IKUS Software
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -13,147 +13,260 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-Created on Mar. 23, 2021
-
-@author: Patrik Dufresne <patrik@ikus-soft.com>
-'''
+import copy
 import logging
-from datetime import datetime
+from datetime import datetime, timezone
+from functools import wraps
+from threading import Event, RLock
 
 import cherrypy
-from apscheduler.executors.pool import ThreadPoolExecutor
-from apscheduler.jobstores.memory import MemoryJobStore
+from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_SUBMITTED
 from apscheduler.schedulers.background import BackgroundScheduler
 from cherrypy.process.plugins import SimplePlugin
 
 logger = logging.getLogger(__name__)
 
 
-def catch_exception(scheduler, func):
+def clear_db_sessions(func):
     """
-    Wrapper function to execute job.
-    Primarly to handle database connection rollback and also to keep track
-    if any job are still running.
+    A decorator that ensures database connections that have become unusable, or are obsolete, are closed
+    before and after the job is executed.
     """
 
-    def wrapper(*args, **kwargs):
-        ident = object()
-        scheduler._running.append(ident)
+    @wraps(func)
+    def func_wrapper(*args, **kwargs):
+        cherrypy.db.clear_sessions()
         try:
-            func(*args, **kwargs)
+            result = func(*args, **kwargs)
         finally:
             cherrypy.db.clear_sessions()
-            scheduler._running.remove(ident)
+        return result
 
-    wrapper._func = func
-    return wrapper
+    return func_wrapper
 
 
 class Scheduler(SimplePlugin):
     """
     Plugins to run Job at fixed time (cronjob) and to schedule task to be run on by one.
+
+    Configuration:
+    - jobstore. Take value 'memory' (default), 'db' to use SQLalchemy database in combination with cherrypy.db. Or any callable function to create an instance of BaseJobStore
     """
 
+    jobstores = {"default": {"type": "memory"}}
+    executors = {"default": {"type": "threadpool", "max_workers": 10}}
+    job_defaults = {"coalesce": False, "max_instances": 1}
+    timezone = None
+
     def __init__(self, bus):
         super().__init__(bus)
-        self._scheduler = self._create_scheduler()
-        self._scheduler.start(paused=True)
-        self._running = []
+        self._scheduler = None
+        # Let keep track of running jobs manually.
+        # This is required for unit testing to wait for all running task.
+        self._lock = RLock()
+        self._event = Event()
+        self._submitted_jobs = set()
+        self._completed_jobs = set()
+
+    @property
+    def _running_jobs(self):
+        with self._lock:
+            return self._submitted_jobs
+
+    def _track_running_jobs(self, event):
+        """
+        This listener keep track of running jobs.
+        This is required to implement wait for tasks mostly used during unit testing.
+        """
+        with self._lock:
+            # Special care must be taken to handle race condition
+            # the EVENT_JOB_EXECUTED may get called before EVENT_JOB_SUBMITTED
+            if event.code == EVENT_JOB_SUBMITTED:
+                if event.job_id in self._completed_jobs:
+                    self._completed_jobs.remove(event.job_id)
+                else:
+                    self._submitted_jobs.add(event.job_id)
+            elif event.code in (EVENT_JOB_EXECUTED, EVENT_JOB_ERROR):
+                if event.job_id in self._submitted_jobs:
+                    self._submitted_jobs.remove(event.job_id)
+                else:
+                    self._completed_jobs.add(event.job_id)
+            # Wakeup wait_for_tasks.
+            self._event.set()
+
+    def _drop_table(self, target, conn, **kwargs):
+        """
+        Callback listener to drop table.
+        This is required because SQLAlchemyJobStore creates the table manually.
+        """
+        from sqlalchemy.sql import ddl
+
+        # Here we need to use private API to loop over all sqlalchemy job store.
+        for jobstore in self._scheduler._jobstores.values():
+            table = getattr(jobstore, 'jobs_t', None)
+            if table is not None:
+                conn.execute(ddl.DropTable(table, if_exists=True))
+
+    def _create_table(self, target, conn, **kwargs):
+        """
+        Callback listener to drop table.
+        This is required because SQLAlchemyJobStore creates the table manually.
+        """
+        from sqlalchemy.sql import ddl
+
+        # Here we need to use private API to loop over all sqlalchemy job store.
+        for jobstore in self._scheduler._jobstores.values():
+            table = getattr(jobstore, 'jobs_t', None)
+            if table is not None:
+                conn.execute(ddl.CreateTable(table, if_not_exists=True))
+
+    def _db_events(self, listen_or_remove):
+        """
+        Listen on database events to create and drop tables as required.
+        """
+        assert listen_or_remove in ['listen', 'remove']
+        try:
+            from sqlalchemy import event
+
+            if getattr(cherrypy, 'db', False):
+                base = cherrypy.db.get_base()
+                func = getattr(event, listen_or_remove)
+                func(base.metadata, 'after_drop', self._drop_table)
+                func(base.metadata, 'after_create', self._create_table)
+        except ImportError:
+            # Nothing to do if sqlalchemy is not available
+            pass
 
     def _create_scheduler(self):
-        return BackgroundScheduler(
-            jobstores={
-                'default': MemoryJobStore(),
-                'scheduled': MemoryJobStore(),
-            },
-            executors={
-                'default': ThreadPoolExecutor(
-                    max_workers=1,
-                    pool_kwargs={'thread_name_prefix': 'scheduler-default'},
-                ),
-                'scheduled': ThreadPoolExecutor(
-                    max_workers=1,
-                    pool_kwargs={'thread_name_prefix': 'scheduler-scheduled'},
-                ),
-            },
+        """
+        Create a new APScheduler base on plugin configuration.
+        """
+        # Create the scheduler with deepcopy of configuration.
+        scheduler = BackgroundScheduler(
+            jobstores=copy.deepcopy(self.jobstores),
+            executors=copy.deepcopy(self.executors),
+            job_defaults=copy.deepcopy(self.job_defaults),
+            timezone=self.timezone,
         )
+        # Add listener to keep track of running jobs.
+        scheduler.add_listener(self._track_running_jobs, (EVENT_JOB_EXECUTED | EVENT_JOB_ERROR | EVENT_JOB_SUBMITTED))
+        # Start the scheduler.
+        scheduler.start()
+        return scheduler
 
     def start(self):
-        self.bus.log('Start Scheduler plugins')
-        self._scheduler.resume()
-        self.bus.subscribe('schedule_job', self.schedule_job)
-        self.bus.subscribe('schedule_task', self.schedule_task)
-        self.bus.subscribe('unschedule_job', self.unschedule_job)
+        self.bus.log('Start Scheduler plugin')
+        # Create apscheduler
+        self._scheduler = self._create_scheduler()
+        # Register drop_table event (when using database)
+        self._db_events('listen')
+        # Then register new channels
+        self.bus.subscribe('scheduler:add_job', self.add_job)
+        self.bus.subscribe('scheduler:add_job_daily', self.add_job_daily)
+        self.bus.subscribe('scheduler:add_job_now', self.add_job_now)
+        self.bus.subscribe('scheduler:remove_job', self.remove_job)
+
+    # Slightly lower priority to start after database, but before other plugins.
+    start.priority = 49
 
     def stop(self):
-        self.bus.log('Stop Scheduler plugins')
-        self._scheduler.pause()
-        self.bus.unsubscribe('schedule_job', self.schedule_job)
-        self.bus.unsubscribe('unschedule_job', self.unschedule_job)
-        self.bus.unsubscribe('schedule_task', self.schedule_task)
-
-    def exit(self):
-        # Shutdown scheduler and create a new one in case the engine get started again.
-        self._scheduler.shutdown(wait=True)
-        self._scheduler = self._create_scheduler()
-        self._scheduler.start(paused=True)
+        self.bus.log('Stop Scheduler plugin')
+        # Unregister drop_table event (when using database)
+        self._db_events('remove')
+        # Shutdown the scheduler & wait for running task to complete.
+        if self._scheduler:
+            self._scheduler.shutdown(wait=True)
+            self._scheduler = None
+        self.bus.unsubscribe('scheduler:add_job', self.add_job)
+        self.bus.unsubscribe('scheduler:add_job_daily', self.add_job_daily)
+        self.bus.unsubscribe('scheduler:add_job_now', self.add_job_now)
+        self.bus.unsubscribe('scheduler:remove_job', self.remove_job)
 
-    def list_jobs(self):
-        """
-        Return list of scheduled jobs.
-        """
-        return self._scheduler.get_jobs(jobstore='scheduled')
+    stop.priority = 51
+
+    def graceful(self):
+        """Reload of subscribers."""
+        self.stop()
+        self.start()
 
-    def list_tasks(self):
+    def add_job(self, func, *args, **kwargs):
         """
-        Return list of tasks.
+        Called via engine.publish('scheduler:add_job', ...)
+        OR directly on the plugin instance.
         """
-        return self._scheduler.get_jobs(jobstore='default')
+        if not self._scheduler:
+            raise RuntimeError("Scheduler not running; cannot add job.")
 
-    def is_job_running(self):
-        return self._running
+        return self._scheduler.add_job(func, *args, **kwargs)
 
-    def schedule_job(self, execution_time, job, *args, **kwargs):
+    def add_job_daily(self, execution_time, func, *args, **kwargs):
         """
-        Add the given scheduled job to the scheduler.
+        A convenience wrapper around add_job() that ensures
+        the job runs daily.
         """
-        assert hasattr(job, '__call__'), 'job must be callable'
         hour, minute = execution_time.split(':', 2)
-        self._scheduler.add_job(
-            func=catch_exception(self, job),
-            name=job.__name__,
+        return self.add_job(
+            func=func,
+            name=getattr(func, '__name__', str(func)),
             args=args,
             kwargs=kwargs,
             trigger='cron',
             hour=hour,
             minute=minute,
-            jobstore='scheduled',
-            executor='scheduled',
+            misfire_grace_time=None,
         )
 
-    def schedule_task(self, task, *args, **kwargs):
+    def add_job_now(self, func, *args, **kwargs):
         """
-        Add the given task to be execute immediately in background.
+        A convenience wrapper around add_job() that ensures
+        the job runs immediately upon being added.
         """
-        assert hasattr(task, '__call__'), 'task must be callable'
-        self._scheduler.add_job(
-            func=catch_exception(self, task),
-            name=task.__name__,
+        return self.add_job(
+            func=func,
+            name=getattr(func, '__name__', str(func)),
             args=args,
             kwargs=kwargs,
-            next_run_time=datetime.now(),
+            next_run_time=datetime.now(timezone.utc),
+            misfire_grace_time=None,
         )
 
-    def unschedule_job(self, job):
+    def get_jobs(self, jobstore=None):
+        """
+        Return list of scheduled jobs.
+        """
+        if not self._scheduler:
+            raise RuntimeError("Scheduler not running; cannot get jobs.")
+        return self._scheduler.get_jobs(jobstore=jobstore)
+
+    def remove_job(self, job, jobstore=None):
         """
         Remove the given job from scheduler.
         """
         # Search for a matching job
-        job_id = next((j.id for j in self._scheduler.get_jobs(jobstore='scheduled') if j.func._func == job), None)
-        if job_id:
-            self._scheduler.remove_job(job_id=job_id, jobstore='scheduled')
+        for j in self._scheduler.get_jobs(jobstore=jobstore):
+            if j.func == job:
+                self._scheduler.remove_job(job_id=j.id, jobstore=jobstore)
+
+    def remove_all_jobs(self, jobstore=None):
+        """
+        Remove all jobs from scheduler.
+        """
+        self._scheduler.remove_all_jobs(jobstore=jobstore)
+
+    def wait_for_jobs(self, jobstore=None):
+        """
+        Used to wait for all running jobs to complete.
+        """
+        # Wait until the queue is empty.
+        while any(
+            job for job in self._scheduler.get_jobs(jobstore=jobstore) if job.next_run_time < datetime.now(timezone.utc)
+        ):
+            self._event.wait(timeout=1)
+            self._event.clear()
+        # Wait until all jobs are completed.
+        while self._running_jobs:
+            self._event.wait(timeout=1)
+            self._event.clear()
 
 
 # Register Scheduler plugin

cherrypy_foundation/plugins/smtp.py

@@ -100,6 +100,26 @@ def _formataddr(value):
     return ', '.join(map(_formataddr, value))
 
 
+def _send_message(server, encryption, username, password, msg):
+    """
+    Send message using SMTP.
+    """
+    host, unused, port = server.partition(':')
+    if encryption == 'ssl':
+        conn = smtplib.SMTP_SSL(host, port or 465)
+    else:
+        conn = smtplib.SMTP(host, port or 25)
+    try:
+        if encryption == 'starttls':
+            conn.starttls()
+        # Authenticate if required.
+        if username:
+            conn.login(username, password)
+        conn.send_message(msg)
+    finally:
+        conn.quit()
+
+
 class SmtpPlugin(SimplePlugin):
 
     server = None
@@ -108,6 +128,32 @@ class SmtpPlugin(SimplePlugin):
     encryption = None
     email_from = None
 
+    def _create_msg(self, subject: str, message: str, to=None, cc=None, bcc=None, reply_to=None, headers={}):
+        assert subject
+        assert message
+        assert to or bcc
+
+        # Record the MIME types of both parts - text/plain and text/html.
+        msg = MIMEMultipart('alternative')
+        msg['Subject'] = str(subject)
+        msg['From'] = _formataddr(self.email_from)
+        if to:
+            msg['To'] = _formataddr(to)
+        if cc:
+            msg['Cc'] = _formataddr(cc)
+        if bcc:
+            msg['Bcc'] = _formataddr(bcc)
+        if reply_to:
+            msg['Reply-To'] = _formataddr(reply_to)
+        msg['Message-ID'] = email.utils.make_msgid()
+        if headers:
+            for key, value in headers.items():
+                msg[key] = value
+        text = _html2plaintext(message)
+        msg.attach(MIMEText(text, 'plain', 'utf8'))
+        msg.attach(MIMEText(message, 'html', 'utf8'))
+        return msg
+
     def start(self):
         self.bus.log('Start SMTP plugin')
         self.bus.subscribe("send_mail", self.send_mail)
@@ -118,70 +164,50 @@ class SmtpPlugin(SimplePlugin):
         self.bus.unsubscribe("send_mail", self.send_mail)
         self.bus.unsubscribe("queue_mail", self.queue_mail)
 
+    def graceful(self):
+        """Reload of subscribers."""
+        self.stop()
+        self.start()
+
     def queue_mail(self, *args, **kwargs):
         """
         Queue mail to be sent.
         """
         # Skip sending email if smtp server is not configured.
         if not self.server:
-            self.bus.log('cannot send email because SMTP Server is not configured')
+            cherrypy.log('cannot send email because SMTP Server is not configured', context='SMTP')
             return
         if not self.email_from:
-            self.bus.log('cannot send email because SMTP From is not configured')
+            cherrypy.log('cannot send email because SMTP From is not configured', context='SMTP')
             return
-        self.bus.publish('schedule_task', self.send_mail, *args, **kwargs)
-
-    def send_mail(self, subject: str, message: str, to=None, cc=None, bcc=None, reply_to=None, headers={}):
+        msg = self._create_msg(*args, **kwargs)
+        self.bus.publish(
+            'scheduler:add_job_now',
+            _send_message,
+            server=self.server,
+            encryption=self.encryption,
+            username=self.username,
+            password=self.password,
+            msg=msg,
+        )
+
+    def send_mail(self, *args, **kwargs):
         """
         Reusable method to be called to send email to the user user.
         `user` user object where to send the email.
         """
-        assert subject
-        assert message
-        assert to or bcc
-
         # Skip sending email if smtp server is not configured.
         if not self.server:
-            self.bus.log('cannot send email because SMTP Server is not configured')
+            cherrypy.log('cannot send email because SMTP Server is not configured', context='SMTP')
             return
         if not self.email_from:
-            self.bus.log('cannot send email because SMTP From is not configured')
+            cherrypy.log('cannot send email because SMTP From is not configured', context='SMTP')
             return
 
-        # Record the MIME types of both parts - text/plain and text/html.
-        msg = MIMEMultipart('alternative')
-        msg['Subject'] = str(subject)
-        msg['From'] = _formataddr(self.email_from)
-        if to:
-            msg['To'] = _formataddr(to)
-        if cc:
-            msg['Cc'] = _formataddr(cc)
-        if bcc:
-            msg['Bcc'] = _formataddr(bcc)
-        if reply_to:
-            msg['Reply-To'] = _formataddr(reply_to)
-        msg['Message-ID'] = email.utils.make_msgid()
-        if headers:
-            for key, value in headers.items():
-                msg[key] = value
-        text = _html2plaintext(message)
-        msg.attach(MIMEText(text, 'plain', 'utf8'))
-        msg.attach(MIMEText(message, 'html', 'utf8'))
-
-        host, unused, port = self.server.partition(':')
-        if self.encryption == 'ssl':
-            conn = smtplib.SMTP_SSL(host, port or 465)
-        else:
-            conn = smtplib.SMTP(host, port or 25)
-        try:
-            if self.encryption == 'starttls':
-                conn.starttls()
-            # Authenticate if required.
-            if self.username:
-                conn.login(self.username, self.password)
-            conn.send_message(msg)
-        finally:
-            conn.quit()
+        msg = self._create_msg(*args, **kwargs)
+        _send_message(
+            server=self.server, encryption=self.encryption, username=self.username, password=self.password, msg=msg
+        )
 
 
 # Register SMTP plugin

cherrypy_foundation/plugins/tests/test_db.py

@@ -93,7 +93,7 @@ else:
             # Given an empty database
             self.assertEqual(0, User.query.count())
             # When calling "/add/" to create a user
-            self.getPage('/add', method='POST', body=urlencode([('username', 'myuser')]))
+            self.getPage('/add', method='POST', body=urlencode({'username': 'myuser'}))
             self.assertStatus(200)
             self.assertInBody('OK')
             # Then user get added to database
@@ -103,7 +103,7 @@ else:
             # Given a database with a users
             User(username='user1').add().commit()
             # When trying to add another user
-            self.getPage('/add', method='POST', body=urlencode([('username', 'user1')]))
+            self.getPage('/add', method='POST', body=urlencode({'username': 'user1'}))
             # Then an error get raised
             self.assertStatus(200)
             self.assertInBody('user_username_unique_ix')

cherrypy_foundation/plugins/tests/test_scheduler.py

@@ -1,5 +1,5 @@
 # Scheduler plugins for Cherrypy
-# Copyright (C) 2022-2025 IKUS Software
+# Copyright (C) 2025 IKUS Software
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -14,79 +14,87 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""
-Created on Oct 17, 2015
-
-@author: Patrik Dufresne <patrik@ikus-soft.com>
-"""
-import importlib.util
-import unittest
-from time import sleep
+from datetime import datetime, timezone
+from threading import Event
 
 import cherrypy
 from cherrypy.test import helper
 
-HAS_APSCHEDULER = importlib.util.find_spec("apscheduler") is not None
+from .. import scheduler  # noqa
+
+done = Event()
 
-if HAS_APSCHEDULER:
-    from .. import scheduler  # noqa
+
+def a_task(*args, **kwargs):
+    done.set()
 
 
-@unittest.skipUnless(HAS_APSCHEDULER, "apscheduler not installed")
 class SchedulerPluginTest(helper.CPWebCase):
     def setUp(self) -> None:
-        self.called = False
+        done.clear()
+        cherrypy.scheduler.remove_all_jobs()
         return super().setUp()
 
+    def tearDown(self):
+        return super().tearDown()
+
     @classmethod
     def setup_server(cls):
         pass
 
-    def test_schedule_job(self):
-        # Given a scheduler with a specific number of jobs
-        count = len(cherrypy.scheduler.list_jobs())
-
-        # Given a job schedule every seconds
-        def a_job(*args, **kwargs):
-            self.called = True
+    def test_add_job(self):
+        # Given a scheduled job
+        scheduled = cherrypy.engine.publish(
+            'scheduler:add_job',
+            a_task,
+            name='custom_name',
+            args=(1, 2, 3),
+            kwargs={'foo': 'bar'},
+            next_run_time=datetime.now(timezone.utc),
+            misfire_grace_time=None,
+        )
+        self.assertTrue(scheduled)
+        self.assertEqual('custom_name', scheduled[0].name)
+        # When waiting for all jobs
+        cherrypy.scheduler.wait_for_jobs()
+        # Then the job is done
+        self.assertTrue(done.is_set())
 
-        scheduled = cherrypy.engine.publish('schedule_job', '23:00', a_job, 1, 2, 3, foo=1, bar=2)
+    def test_add_job_daily(self):
+        # Given a scheduler with a specific number of jobs
+        count = len(cherrypy.scheduler.get_jobs())
+        # When scheduling a daily job.
+        scheduled = cherrypy.engine.publish('scheduler:add_job_daily', '23:00', a_task, 1, 2, 3, foo=1, bar=2)
+        # Then the job is scheduled
         self.assertTrue(scheduled)
-        self.assertEqual(count + 1, len(cherrypy.scheduler.list_jobs()))
+        self.assertEqual('a_task', scheduled[0].name)
+        # Then the number of jobs increase.
+        self.assertEqual(count + 1, len(cherrypy.scheduler.get_jobs()))
 
-    def test_scheduler_task(self):
+    def test_add_job_now(self):
         # Given a task
-
-        def a_task(*args, **kwargs):
-            self.called = True
-
         # When scheduling that task
-        scheduled = cherrypy.engine.publish('schedule_task', a_task, 1, 2, 3, foo=1, bar=2)
+        scheduled = cherrypy.engine.publish('scheduler:add_job_now', a_task, 1, 2, 3, foo=1, bar=2)
         self.assertTrue(scheduled)
-        sleep(1)
-        while len(cherrypy.scheduler.list_tasks()) >= 1:
-            sleep(1)
+        # When waiting for all tasks
+        cherrypy.scheduler.wait_for_jobs()
         # Then the task get called
-        self.assertTrue(self.called)
+        self.assertTrue(done.is_set())
 
-    def test_unschedule_job(self):
+    def test_remove_job(self):
         # Given a scheduler with a specific number of jobs
-        count = len(cherrypy.scheduler.list_jobs())
-
+        count = len(cherrypy.scheduler.get_jobs())
         # Given a job schedule every seconds
-        def a_job(*args, **kwargs):
-            self.called = True
-
-        cherrypy.engine.publish('schedule_job', '23:00', a_job, 1, 2, 3, foo=1, bar=2)
-        self.assertEqual(count + 1, len(cherrypy.scheduler.list_jobs()))
-        cherrypy.engine.publish('unschedule_job', a_job)
-        self.assertEqual(count, len(cherrypy.scheduler.list_jobs()))
-
-    def test_unschedule_job_with_invalid_job(self):
+        cherrypy.engine.publish('scheduler:add_job_daily', '23:00', a_task, 1, 2, 3, foo=1, bar=2)
+        # Then number of job increase
+        self.assertEqual(count + 1, len(cherrypy.scheduler.get_jobs()))
+        # When the job is unscheduled.
+        cherrypy.engine.publish('scheduler:remove_job', a_task)
+        # Then the number of job decrease.
+        self.assertEqual(count, len(cherrypy.scheduler.get_jobs()))
+
+    def test_remove_job_with_invalid_job(self):
         # Given an unschedule job
-        def a_job(*args, **kwargs):
-            self.called = True
-
         # When unscheduling an invalid job
-        cherrypy.engine.publish('unschedule_job', a_job)
-        # Then no error are raised
+        cherrypy.engine.publish('scheduler:remove_job', a_task)
+        # Then an error is not raised.