WuttaWeb 0.31.1__py3-none-any.whl

wuttaweb/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  wuttaweb -- Web App for Wutta Framework
+#  Copyright © 2024 Lance Edgar
+#
+#  This file is part of Wutta Framework.
+#
+#  Wutta Framework 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.
+#
+#  Wutta Framework 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
+#  Wutta Framework.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+wuttaweb - base package for web app
+"""
+
+from ._version import __version__

wuttaweb/_version.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8; -*-
+"""
+Package Version
+"""
+
+from importlib.metadata import version
+
+
+__version__ = version("wuttaweb")

wuttaweb/app.py

@@ -0,0 +1,295 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  wuttaweb -- Web App for Wutta Framework
+#  Copyright © 2024-2025 Lance Edgar
+#
+#  This file is part of Wutta Framework.
+#
+#  Wutta Framework 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.
+#
+#  Wutta Framework 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
+#  Wutta Framework.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Application
+"""
+
+import logging
+import os
+
+from wuttjamaican.app import AppProvider
+from wuttjamaican.conf import make_config
+
+from asgiref.wsgi import WsgiToAsgi
+from pyramid.config import Configurator
+
+import wuttaweb.db
+from wuttaweb.auth import WuttaSecurityPolicy
+from wuttaweb.util import get_effective_theme, get_theme_template_path
+
+
+log = logging.getLogger(__name__)
+
+
+class WebAppProvider(AppProvider):
+    """
+    The :term:`app provider` for WuttaWeb.  This adds some methods to
+    the :term:`app handler`, which are specific to web apps.  It also
+    registers some :term:`email templates <email template>` for the
+    app, etc.
+    """
+
+    email_modules = ["wuttaweb.emails"]
+    email_templates = ["wuttaweb:email-templates"]
+
+    def get_web_handler(self):
+        """
+        Get the configured "web" handler for the app.
+
+        Specify a custom handler in your config file like this:
+
+        .. code-block:: ini
+
+           [wutta]
+           web.handler_spec = poser.web.handler:PoserWebHandler
+
+        :returns: Instance of :class:`~wuttaweb.handler.WebHandler`.
+        """
+        if "web" not in self.app.handlers:
+            spec = self.config.get(
+                f"{self.appname}.web.handler_spec",
+                default="wuttaweb.handler:WebHandler",
+            )
+            self.app.handlers["web"] = self.app.load_object(spec)(self.config)
+        return self.app.handlers["web"]
+
+
+def make_wutta_config(settings, config_maker=None, **kwargs):
+    """
+    Make a WuttaConfig object from the given settings.
+
+    Note that ``settings`` dict will (typically) correspond to the
+    ``[app:main]`` section of your config file.
+
+    Regardless, the ``settings`` must contain a special key/value
+    which is needed to identify the location of the config file.
+    Assuming the typical scenario then, your config file should have
+    an entry like this:
+
+    .. code-block:: ini
+
+       [app:main]
+       wutta.config = %(__file__)s
+
+    The ``%(__file__)s`` is auto-replaced with the config file path,
+    so ultimately ``settings`` would contain something like (at
+    minimum)::
+
+       {'wutta.config': '/path/to/config/file'}
+
+    If this config file path cannot be discovered, an error is raised.
+    """
+    wutta_config = settings.get("wutta_config")
+    if not wutta_config:
+
+        # validate config file path
+        path = settings.get("wutta.config")
+        if not path or not os.path.exists(path):
+            raise ValueError(
+                "Please set 'wutta.config' in [app:main] "
+                "section of config to the path of your "
+                "config file.  Lame, but necessary."
+            )
+
+        # make config, add to settings
+        config_maker = config_maker or make_config
+        wutta_config = config_maker(path, **kwargs)
+        settings["wutta_config"] = wutta_config
+
+    # configure database sessions
+    if hasattr(wutta_config, "appdb_engine"):
+        wuttaweb.db.Session.configure(bind=wutta_config.appdb_engine)
+
+    return wutta_config
+
+
+def make_pyramid_config(settings):
+    """
+    Make and return a Pyramid config object from the given settings.
+
+    The config is initialized with certain features deemed useful for
+    all apps.
+
+    :returns: Instance of
+       :class:`pyramid:pyramid.config.Configurator`.
+    """
+    settings.setdefault("fanstatic.versioning", "true")
+    settings.setdefault("mako.directories", ["wuttaweb:templates"])
+    settings.setdefault(
+        "pyramid_deform.template_search_path", "wuttaweb:templates/deform"
+    )
+
+    # update settings per current theme
+    establish_theme(settings)
+
+    pyramid_config = Configurator(settings=settings)
+
+    # configure user authorization / authentication
+    pyramid_config.set_security_policy(WuttaSecurityPolicy())
+
+    # require CSRF token for POST
+    pyramid_config.set_default_csrf_options(
+        require_csrf=True, token="_csrf", header="X-CSRF-TOKEN"
+    )
+
+    pyramid_config.include("pyramid_beaker")
+    pyramid_config.include("pyramid_deform")
+    pyramid_config.include("pyramid_fanstatic")
+    pyramid_config.include("pyramid_mako")
+    pyramid_config.include("pyramid_tm")
+
+    # add some permissions magic
+    pyramid_config.add_directive(
+        "add_wutta_permission_group", "wuttaweb.auth.add_permission_group"
+    )
+    pyramid_config.add_directive("add_wutta_permission", "wuttaweb.auth.add_permission")
+
+    # add some more config magic
+    pyramid_config.add_directive(
+        "add_wutta_master_view", "wuttaweb.conf.add_master_view"
+    )
+
+    return pyramid_config
+
+
+def main(global_config, **settings):  # pylint: disable=unused-argument
+    """
+    Make and return the WSGI application, per given settings.
+
+    This function is designed to be called via Paste, hence it does
+    require params and therefore can't be used directly as app factory
+    for general WSGI servers.  For the latter see
+    :func:`make_wsgi_app()` instead.
+
+    And this *particular* function is not even that useful, it only
+    constructs an app with minimal views built-in to WuttaWeb.  Most
+    apps will define their own ``main()`` function (e.g.  as
+    ``poser.web.app:main``), similar to this one but with additional
+    views and other config.
+    """
+    wutta_config = make_wutta_config(settings)  # pylint: disable=unused-variable
+    pyramid_config = make_pyramid_config(settings)
+
+    pyramid_config.include("wuttaweb.static")
+    pyramid_config.include("wuttaweb.subscribers")
+    pyramid_config.include("wuttaweb.views")
+
+    return pyramid_config.make_wsgi_app()
+
+
+def make_wsgi_app(main_app=None, config=None):
+    """
+    Make and return a WSGI app, using the given Paste app factory.
+
+    See also :func:`make_asgi_app()` for the ASGI equivalent.
+
+    This function could be used directly for general WSGI servers
+    (e.g. uvicorn), ***if*** you just want the built-in :func:`main()`
+    app factory.
+
+    But most likely you do not, in which case you must define your own
+    function and call this one with your preferred app factory::
+
+       from wuttaweb.app import make_wsgi_app
+
+       def my_main(global_config, **settings):
+           # TODO: build your app
+           pass
+
+       def make_my_wsgi_app():
+           return make_wsgi_app(my_main)
+
+    So ``make_my_wsgi_app()`` could then be used as-is for general
+    WSGI servers.  However, note that this approach will require
+    setting the ``WUTTA_CONFIG_FILES`` environment variable, unless
+    running via :ref:`wutta-webapp`.
+
+    :param main_app: Either a Paste-compatible app factory, or
+       :term:`spec` for one.  If not specified, the built-in
+       :func:`main()` is assumed.
+
+    :param config: Optional :term:`config object`.  If not specified,
+       one is created based on ``WUTTA_CONFIG_FILES`` environment
+       variable.
+    """
+    if not config:
+        config = make_config()
+    app = config.get_app()
+
+    # extract pyramid settings
+    settings = config.get_dict("app:main")
+
+    # keep same config object
+    settings["wutta_config"] = config
+
+    # determine the app factory
+    if isinstance(main_app, str):
+        factory = app.load_object(main_app)
+    elif callable(main_app):
+        factory = main_app
+    else:
+        raise ValueError("main_app must be spec or callable")
+
+    # construct a pyramid app "per usual"
+    return factory({}, **settings)
+
+
+def make_asgi_app(main_app=None, config=None):
+    """
+    Make and return a ASGI app, using the given Paste app factory.
+
+    This works the same as :func:`make_wsgi_app()` and should be
+    called in the same way etc.
+    """
+    wsgi_app = make_wsgi_app(main_app, config=config)
+    return WsgiToAsgi(wsgi_app)
+
+
+def establish_theme(settings):
+    """
+    Establishes initial theme on app startup.  This mostly involves
+    updating the given ``settings`` dict.
+
+    This function is called automatically from within
+    :func:`make_pyramid_config()`.
+
+    It will first call :func:`~wuttaweb.util.get_effective_theme()` to
+    read the current theme from the :term:`settings table`, and store
+    this within ``settings['wuttaweb.theme']``.
+
+    It then calls :func:`~wuttaweb.util.get_theme_template_path()` and
+    will update ``settings['mako.directories']`` such that the theme's
+    template path is listed first.
+    """
+    config = settings["wutta_config"]
+
+    theme = get_effective_theme(config)
+    settings["wuttaweb.theme"] = theme
+
+    directories = settings["mako.directories"]
+    if isinstance(directories, str):
+        directories = config.parse_list(directories)
+
+    path = get_theme_template_path(config)
+    directories.insert(0, path)
+    settings["mako.directories"] = directories

wuttaweb/auth.py

@@ -0,0 +1,252 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  wuttaweb -- Web App for Wutta Framework
+#  Copyright © 2024-2025 Lance Edgar
+#
+#  This file is part of Wutta Framework.
+#
+#  Wutta Framework 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.
+#
+#  Wutta Framework 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
+#  Wutta Framework.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Auth Utility Logic
+"""
+
+from pyramid.authentication import SessionAuthenticationHelper
+from pyramid.request import RequestLocalCache
+from pyramid.security import remember, forget
+
+from wuttaweb.db import Session
+
+
+def login_user(request, user):
+    """
+    Perform the steps necessary to "login" the given user.  This
+    returns a ``headers`` dict which you should pass to the final
+    redirect, like so::
+
+       from pyramid.httpexceptions import HTTPFound
+
+       headers = login_user(request, user)
+       return HTTPFound(location='/', headers=headers)
+
+    .. warning::
+
+       This logic does not "authenticate" the user!  It assumes caller
+       has already authenticated the user and they are safe to login.
+
+    See also :func:`logout_user()`.
+    """
+    headers = remember(request, user.uuid)
+    return headers
+
+
+def logout_user(request):
+    """
+    Perform the logout action for the given request.  This returns a
+    ``headers`` dict which you should pass to the final redirect, like
+    so::
+
+       from pyramid.httpexceptions import HTTPFound
+
+       headers = logout_user(request)
+       return HTTPFound(location='/', headers=headers)
+
+    See also :func:`login_user()`.
+    """
+    request.session.delete()
+    request.session.invalidate()
+    headers = forget(request)
+    return headers
+
+
+class WuttaSecurityPolicy:
+    """
+    Pyramid :term:`security policy` for WuttaWeb.
+
+    For more on the Pyramid details, see :doc:`pyramid:narr/security`.
+
+    But the idea here is that you should be able to just use this,
+    without thinking too hard::
+
+       from pyramid.config import Configurator
+       from wuttaweb.auth import WuttaSecurityPolicy
+
+       pyramid_config = Configurator()
+       pyramid_config.set_security_policy(WuttaSecurityPolicy())
+
+    This security policy will then do the following:
+
+    * use the request "web session" for auth storage (e.g. current
+      ``user.uuid``)
+    * check permissions as needed, by calling
+      :meth:`~wuttjamaican:wuttjamaican.auth.AuthHandler.has_permission()`
+      for current user
+
+    :param db_session: Optional :term:`db session` to use, instead of
+       :class:`wuttaweb.db.sess.Session`.  Probably only useful for
+       tests.
+    """
+
+    def __init__(self, db_session=None):
+        self.session_helper = SessionAuthenticationHelper()
+        self.identity_cache = RequestLocalCache(self.load_identity)
+        self.db_session = db_session or Session()
+
+    def load_identity(self, request):  # pylint: disable=empty-docstring
+        """ """
+        config = request.registry.settings["wutta_config"]
+        app = config.get_app()
+        model = app.model
+
+        # fetch user uuid from current session
+        uuid = self.session_helper.authenticated_userid(request)
+        if not uuid:
+            return None
+
+        # fetch user object from db
+        user = self.db_session.get(model.User, uuid)
+        if not user:
+            return None
+
+        return user
+
+    def identity(self, request):  # pylint: disable=empty-docstring
+        """ """
+        return self.identity_cache.get_or_create(request)
+
+    def authenticated_userid(self, request):  # pylint: disable=empty-docstring
+        """ """
+        user = self.identity(request)
+        if user is not None:
+            return user.uuid
+        return None
+
+    def remember(self, request, userid, **kw):  # pylint: disable=empty-docstring
+        """ """
+        return self.session_helper.remember(request, userid, **kw)
+
+    def forget(self, request, **kw):  # pylint: disable=empty-docstring
+        """ """
+        return self.session_helper.forget(request, **kw)
+
+    def permits(  # pylint: disable=unused-argument,empty-docstring
+        self, request, context, permission
+    ):
+        """ """
+
+        # nb. root user can do anything
+        if getattr(request, "is_root", False):
+            return True
+
+        config = request.registry.settings["wutta_config"]
+        app = config.get_app()
+        auth = app.get_auth_handler()
+        user = self.identity(request)
+        return auth.has_permission(self.db_session, user, permission)
+
+
+def add_permission_group(pyramid_config, groupkey, label=None, overwrite=True):
+    """
+    Pyramid directive to add a "permission group" to the app's
+    awareness.
+
+    The app must be made aware of all permissions, so they are exposed
+    when editing a
+    :class:`~wuttjamaican:wuttjamaican.db.model.auth.Role`.  The logic
+    for discovering permissions is in
+    :meth:`~wuttaweb.views.roles.RoleView.get_available_permissions()`.
+
+    This is usually called from within a master view's
+    :meth:`~wuttaweb.views.master.MasterView.defaults()` to establish
+    the permission group which applies to the view model.
+
+    A simple example of usage::
+
+       pyramid_config.add_permission_group('widgets', label="Widgets")
+
+    :param groupkey: Unique key for the permission group.  In the
+       context of a master view, this will be the same as
+       :attr:`~wuttaweb.views.master.MasterView.permission_prefix`.
+
+    :param label: Optional label for the permission group.  If not
+       specified, it is derived from ``groupkey``.
+
+    :param overwrite: If the permission group was already established,
+       this flag controls whether the group's label should be
+       overwritten (with ``label``).
+
+    See also :func:`add_permission()`.
+    """
+    config = pyramid_config.get_settings()["wutta_config"]
+    app = config.get_app()
+
+    def action():
+        perms = pyramid_config.get_settings().get("wutta_permissions", {})
+        if overwrite or groupkey not in perms:
+            group = perms.setdefault(groupkey, {"key": groupkey})
+            group["label"] = label or app.make_title(groupkey)
+        pyramid_config.add_settings({"wutta_permissions": perms})
+
+    pyramid_config.action(None, action)
+
+
+def add_permission(pyramid_config, groupkey, key, label=None):
+    """
+    Pyramid directive to add a single "permission" to the app's
+    awareness.
+
+    The app must be made aware of all permissions, so they are exposed
+    when editing a
+    :class:`~wuttjamaican:wuttjamaican.db.model.auth.Role`.  The logic
+    for discovering permissions is in
+    :meth:`~wuttaweb.views.roles.RoleView.get_available_permissions()`.
+
+    This is usually called from within a master view's
+    :meth:`~wuttaweb.views.master.MasterView.defaults()` to establish
+    "known" permissions based on master view feature flags
+    (:attr:`~wuttaweb.views.master.MasterView.viewable`,
+    :attr:`~wuttaweb.views.master.MasterView.editable`, etc.).
+
+    A simple example of usage::
+
+       pyramid_config.add_permission('widgets', 'widgets.polish',
+                                     label="Polish all the widgets")
+
+    :param groupkey: Unique key for the permission group.  In the
+       context of a master view, this will be the same as
+       :attr:`~wuttaweb.views.master.MasterView.permission_prefix`.
+
+    :param key: Unique key for the permission.  This should be the
+       "complete" permission name which includes the permission
+       prefix.
+
+    :param label: Optional label for the permission.  If not
+       specified, it is derived from ``key``.
+
+    See also :func:`add_permission_group()`.
+    """
+
+    def action():
+        config = pyramid_config.get_settings()["wutta_config"]
+        app = config.get_app()
+        perms = pyramid_config.get_settings().get("wutta_permissions", {})
+        group = perms.setdefault(groupkey, {"key": groupkey})
+        group.setdefault("label", app.make_title(groupkey))
+        perm = group.setdefault("perms", {}).setdefault(key, {"key": key})
+        perm["label"] = label or app.make_title(key)
+        pyramid_config.add_settings({"wutta_permissions": perms})
+
+    pyramid_config.action(None, action)

wuttaweb/cleanup.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  wuttaweb -- Web App for Wutta Framework
+#  Copyright © 2024-2026 Lance Edgar
+#
+#  This file is part of Wutta Framework.
+#
+#  Wutta Framework 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.
+#
+#  Wutta Framework 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
+#  Wutta Framework.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Cleanup for WuttaWeb
+"""
+
+import os
+import logging
+import time
+
+from wuttjamaican.cleanup import Cleaner
+
+
+log = logging.getLogger(__name__)
+
+
+class WuttaWebCleaner(Cleaner):
+    """
+    This :term:`cleaner` removes old Beaker session files.
+    """
+
+    def cleanup(self, dry_run=False):
+        """
+        This first calls :meth:`get_beaker_session_dir()` and then
+        iterates over the contents, looking for files older than the
+        cutoff (default is 30 days).  Such files will be deleted
+        unless ``dry_mode`` is specified.
+        """
+        session_dir = self.get_beaker_session_dir()
+        if not session_dir:
+            log.debug("Beaker session folder could not be located")
+            return
+
+        data_dir = os.path.join(session_dir, "data")
+        lock_dir = os.path.join(session_dir, "lock")
+
+        # looking for files older than X days
+        days = self.config.get_int(
+            f"{self.config.appname}.cleanup.wuttaweb.beaker_session_cutoff_days",
+            default=30,
+        )
+        cutoff = time.time() - 3600 * 24 * days
+
+        for topdir in (data_dir, lock_dir):
+            if not os.path.isdir(topdir):
+                continue
+
+            for (  # pylint: disable=unused-variable
+                dirpath,
+                dirnames,
+                filenames,
+            ) in os.walk(topdir):
+                for fname in filenames:
+                    path = os.path.join(dirpath, fname)
+                    ts = os.path.getmtime(path)
+                    if ts <= cutoff:
+                        if dry_run:
+                            log.debug("would delete file: %s", path)
+                        else:
+                            os.remove(path)
+                            log.debug("deleted file: %s", path)
+
+    def get_beaker_session_dir(self):
+        """
+        Retrieve the path to Beaker session storage folder.
+
+        By default this will be at ``venv/app/cache/sessions`` but it
+        can be overridden via config.
+
+        :returns: Path as string, or ``None`` if it could not be
+           determined.
+        """
+        if path := self.config.get(
+            f"{self.config.appname}.cleanup.wuttaweb.beaker_session_dir"
+        ):
+            return path
+
+        path = self.app.get_appdir("cache", "sessions")
+        if os.path.isdir(path):
+            return path
+
+        return None