cherrypy-foundation 1.0.0__py3-none-any.whl

cherrypy_foundation/plugins/scheduler.py

@@ -0,0 +1,287 @@
+# Scheduler plugins for Cherrypy
+# Copyright (C) 2026 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
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+import copy
+import logging
+from datetime import datetime, timezone
+from functools import wraps
+from threading import Event, RLock
+
+import cherrypy
+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 clear_db_sessions(func):
+    """
+    A decorator that ensures database connections that have become unusable, or are obsolete, are closed
+    before and after the job is executed.
+    """
+
+    @wraps(func)
+    def func_wrapper(*args, **kwargs):
+        try:
+            result = func(*args, **kwargs)
+        finally:
+            cherrypy.db.clear_sessions()
+        return result
+
+    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 = 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):
+        """
+        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 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 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)
+
+    stop.priority = 51
+
+    def graceful(self):
+        """Reload of subscribers."""
+        self.stop()
+        self.start()
+
+    def add_job(self, func, *args, **kwargs):
+        """
+        Called via engine.publish('scheduler:add_job', ...)
+        OR directly on the plugin instance.
+        """
+        if not self._scheduler:
+            raise RuntimeError("Scheduler not running; cannot add job.")
+
+        return self._scheduler.add_job(func, *args, **kwargs)
+
+    def add_job_daily(self, execution_time, func, *args, **kwargs):
+        """
+        A convenience wrapper around add_job() that ensures
+        the job runs daily.
+        """
+        hour, minute = execution_time.split(':', 2)
+        return self.add_job(
+            id=getattr(func, '__name__', str(func)),
+            func=func,
+            name=getattr(func, '__name__', str(func)),
+            args=args,
+            kwargs=kwargs,
+            trigger='cron',
+            hour=hour,
+            minute=minute,
+            misfire_grace_time=None,
+            coalesce=True,
+            replace_existing=True,
+        )
+
+    def add_job_now(self, func, *args, **kwargs):
+        """
+        A convenience wrapper around add_job() that ensures
+        the job runs immediately upon being added.
+        """
+        return self.add_job(
+            func=func,
+            name=getattr(func, '__name__', str(func)),
+            args=args,
+            kwargs=kwargs,
+            next_run_time=datetime.now(timezone.utc),
+            misfire_grace_time=None,
+        )
+
+    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
+        return_value = False
+        if self._scheduler is None:
+            return return_value
+        for j in self._scheduler.get_jobs(jobstore=jobstore):
+            if j.func == job or j.name == job:
+                self._scheduler.remove_job(job_id=j.id, jobstore=jobstore)
+                return_value = True
+        return return_value
+
+    def remove_all_jobs(self, jobstore=None):
+        """
+        Remove all jobs from scheduler.
+        """
+        if self._scheduler is None:
+            return
+        self._scheduler.remove_all_jobs(jobstore=jobstore)
+
+    def wait_for_jobs(self, jobstore=None):
+        """
+        Used to wait for all running jobs to complete.
+        """
+        if self._scheduler is None:
+            return
+        # 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.scheduler = Scheduler(cherrypy.engine)
+cherrypy.scheduler.subscribe()
+
+cherrypy.config.namespaces['scheduler'] = lambda key, value: setattr(cherrypy.scheduler, key, value)

cherrypy_foundation/plugins/smtp.py

@@ -0,0 +1,223 @@
+# SMTP Plugins for cherrypy
+# Copyright (C) 2026 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
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import email.utils
+import re
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from xml.etree.ElementTree import fromstring, tostring
+
+import cherrypy
+from cherrypy.process.plugins import SimplePlugin
+
+
+def _html2plaintext(html, encoding='utf-8'):
+    """From an HTML text, convert the HTML to plain text.
+    If @param body_id is provided then this is the tag where the
+    body (not necessarily <body>) starts.
+    """
+    # (c) Fry-IT, www.fry-it.com, 2007
+    # <peter@fry-it.com>
+    # download here: http://www.peterbe.com/plog/html2plaintext
+    assert isinstance(html, str)
+    # &#160; are non-breaking space
+    html = html.replace('&#160;', ' ')
+    url_index = []
+    try:
+        tree = fromstring(html)
+        tree = tree.find('body')
+        i = 0
+        for link in tree.findall('.//a'):
+            url = link.get('href')
+            if url:
+                i += 1
+                link.tag = 'span'
+                link.text = '%s [%s]' % (link.text, i)
+                url_index.append(url)
+        html = tostring(tree, encoding=encoding).decode(encoding)
+    except Exception:
+        # Don't fail if the html is invalid.
+        pass
+    # \r char is converted into &#13;, must remove it
+    html = html.replace('&#13;', '')
+    # Remove new line & spaces defined for html formating.
+    html = re.sub('\n *', '', html)
+    # Replace tags
+    html = html.replace('<strong>', '*').replace('</strong>', '*')
+    html = html.replace('<b>', '*').replace('</b>', '*')
+    html = html.replace('<h3>', '*').replace('</h3>', '*')
+    html = html.replace('<h2>', '**').replace('</h2>', '**\n')
+    html = html.replace('<h1>', '**').replace('</h1>', '**\n')
+    html = html.replace('<em>', '/').replace('</em>', '/')
+    html = html.replace('<tr>', '\n')
+    html = html.replace('</p>', '\n')
+    html = re.sub('<style[^>]*>[^<]*</style>', '', html)
+    html = re.sub(r'<br\s*/?>', '\n', html)
+    html = re.sub('<[^>]*>', '', html)
+    html = re.sub(r'\n+', '\n', html)
+    html = html.replace('&gt;', '>')
+    html = html.replace('&lt;', '<')
+    html = html.replace('&amp;', '&')
+
+    # strip all lines
+    html = '\n'.join([x.strip() for x in html.splitlines()])
+    html = html.replace('\n' * 2, '\n')
+
+    for i, url in enumerate(url_index):
+        if i == 0:
+            html += '\n\n'
+        html += '[%s] %s\n' % (i + 1, url)
+
+    return html.strip('\n')
+
+
+def _formataddr(value):
+    """
+    Format the given value into a valid email address. Support raw string, tuple or a list of string.
+    """
+    if not value:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (tuple, list)) and len(value) == 2 and isinstance(value[0], str) and isinstance(value[1], str):
+        return email.utils.formataddr(value)
+    if not isinstance(value, (tuple, list)):
+        raise TypeError('expect a string, a tuple or a list of email address')
+    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
+    username = None
+    password = None
+    encryption = None
+    email_from = None
+    bcc = 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)
+        bcc_list = []
+        if self.bcc:
+            bcc_list.append(_formataddr(self.bcc))
+        if bcc:
+            bcc_list.append(_formataddr(bcc))
+        if bcc_list:
+            msg['Bcc'] = ', '.join(bcc_list)
+        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)
+        self.bus.subscribe("queue_mail", self.queue_mail)
+
+    def stop(self):
+        self.bus.log('Stop SMTP plugin')
+        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:
+            cherrypy.log('cannot send email because SMTP Server is not configured', context='SMTP')
+            return
+        if not self.email_from:
+            cherrypy.log('cannot send email because SMTP From is not configured', context='SMTP')
+            return
+        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.
+        """
+        # Skip sending email if smtp server is not configured.
+        if not self.server:
+            cherrypy.log('cannot send email because SMTP Server is not configured', context='SMTP')
+            return
+        if not self.email_from:
+            cherrypy.log('cannot send email because SMTP From is not configured', context='SMTP')
+            return
+
+        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.smtp = SmtpPlugin(cherrypy.engine)
+cherrypy.smtp.subscribe()
+
+cherrypy.config.namespaces['smtp'] = lambda key, value: setattr(cherrypy.smtp, key, value)

cherrypy_foundation/plugins/tests/test_db.py

@@ -0,0 +1,118 @@
+# Cherrypy-foundation
+# Copyright (C) 2022-2026 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
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+import importlib
+import tempfile
+import unittest
+from urllib.parse import urlencode
+
+import cherrypy
+from cherrypy.test import helper
+
+HAS_SQLALCHEMY = importlib.util.find_spec("sqlalchemy") is not None
+
+if not HAS_SQLALCHEMY:
+    pass
+else:
+    from sqlalchemy import Column, Integer, String, func
+    from sqlalchemy.exc import IntegrityError
+    from sqlalchemy.sql.schema import Index
+
+    from .. import db  # noqa
+
+    Base = cherrypy.db.get_base()
+
+    class User(Base):
+        __tablename__ = 'users'
+        id = Column(Integer, primary_key=True)
+        username = Column(String)
+
+        def __repr__(self):
+            return f"User(id={self.id}, username='{self.username}')"
+
+    Index('user_username_unique_ix', func.lower(User.username), unique=True, info='This username already exists.')
+
+    class Root:
+
+        @cherrypy.expose
+        def index(self):
+            return str(User.query.all())
+
+        @cherrypy.expose
+        def add(self, username):
+            try:
+                User(username=username).add().commit()
+                return "OK"
+            except IntegrityError as e:
+                return str(e)
+
+    @unittest.skipUnless(HAS_SQLALCHEMY, "sqlalchemy not installed")
+    class DbPluginTest(helper.CPWebCase):
+        interactive = False
+
+        @classmethod
+        def setup_class(cls):
+            cls.tempdir = tempfile.TemporaryDirectory(prefix='cherrypy-foundation-', suffix='-db-test')
+            super().setup_class()
+
+        @classmethod
+        def teardown_class(cls):
+            cls.tempdir.cleanup()
+            super().teardown_class()
+
+        @classmethod
+        def setup_server(cls):
+            cherrypy.config.update(
+                {
+                    'db.uri': f"sqlite:///{cls.tempdir.name}/data.db",
+                }
+            )
+            cherrypy.tree.mount(Root(), '/')
+
+        def setUp(self):
+            cherrypy.db.create_all()
+            return super().setUp()
+
+        def tearDown(self):
+            cherrypy.db.drop_all()
+            return super().tearDown()
+
+        def test_add_user(self):
+            # 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.assertStatus(200)
+            self.assertInBody('OK')
+            # Then user get added to database
+            self.assertEqual(1, User.query.count())
+
+        def test_add_duplicate_user(self):
+            # 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'}))
+            # Then an error get raised
+            self.assertStatus(200)
+            self.assertInBody('user_username_unique_ix')
+
+        def test_get_users(self):
+            # Given a database with a users
+            new_user = User(username='newuser').add().commit()
+            # When calling "/"
+            self.getPage("/")
+            self.assertStatus(200)
+            # Then the page include our users
+            self.assertInBody(new_user.username)