WuttaWeb 0.17.2__tar.gz → 0.19.0__tar.gz

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to wuttaweb will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## v0.19.0 (2024-12-23)
+
+### Feat
+
+- add feature to edit email settings, basic message preview
+
+### Fix
+
+- move CRUD header buttons toward center of screen
+
+## v0.18.0 (2024-12-18)
+
+### Feat
+
+- add basic support for running in ASGI context
+- add support for running via uvicorn; `wutta webapp` command
+
 ## v0.17.2 (2024-12-17)
 
 ### Fix

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: WuttaWeb
-Version: 0.17.2
+Version: 0.19.0
 Summary: Web App for Wutta Framework
 Project-URL: Homepage, https://wuttaproject.org/
 Project-URL: Repository, https://forgejo.wuttaproject.org/wutta/wuttaweb
@@ -25,6 +25,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
+Requires-Dist: asgiref
 Requires-Dist: colanderalchemy
 Requires-Dist: humanize
 Requires-Dist: markdown
@@ -38,20 +39,21 @@ Requires-Dist: pyramid-tm
 Requires-Dist: pyramid>=2
 Requires-Dist: waitress
 Requires-Dist: webhelpers2
-Requires-Dist: wuttjamaican[db]>=0.18.0
+Requires-Dist: wuttjamaican[db]>=0.19.0
 Requires-Dist: zope-sqlalchemy>=1.5
 Provides-Extra: continuum
 Requires-Dist: wutta-continuum; extra == 'continuum'
 Provides-Extra: docs
 Requires-Dist: furo; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinxcontrib-programoutput; extra == 'docs'
 Provides-Extra: tests
 Requires-Dist: pytest-cov; extra == 'tests'
 Requires-Dist: tox; extra == 'tests'
 Description-Content-Type: text/markdown
 
 
-# wuttaweb
+# WuttaWeb
 
 Web app for Wutta Framework
 

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/README.md

@@ -1,5 +1,5 @@
 
-# wuttaweb
+# WuttaWeb
 
 Web app for Wutta Framework
 

wuttaweb-0.19.0/docs/api/wuttaweb.cli.rst

@@ -0,0 +1,6 @@
+
+``wuttaweb.cli``
+================
+
+.. automodule:: wuttaweb.cli
+   :members:

wuttaweb-0.19.0/docs/api/wuttaweb.cli.webapp.rst

@@ -0,0 +1,6 @@
+
+``wuttaweb.cli.webapp``
+=======================
+
+.. automodule:: wuttaweb.cli.webapp
+   :members:

wuttaweb-0.19.0/docs/api/wuttaweb.emails.rst

@@ -0,0 +1,6 @@
+
+``wuttaweb.emails``
+===================
+
+.. automodule:: wuttaweb.emails
+   :members:

wuttaweb-0.19.0/docs/api/wuttaweb.views.email.rst

@@ -0,0 +1,6 @@
+
+``wuttaweb.views.email``
+========================
+
+.. automodule:: wuttaweb.views.email
+   :members:

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/docs/conf.py

@@ -21,6 +21,7 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
+    'sphinxcontrib.programoutput',
 ]
 
 templates_path = ['_templates']

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/docs/index.rst

@@ -19,6 +19,7 @@ the narrative docs are pretty scant.  That will eventually change.
    :caption: Documentation:
 
    glossary
+   narr/cli/index
    narr/templates/index
 
 .. toctree::
@@ -28,10 +29,13 @@ the narrative docs are pretty scant.  That will eventually change.
    api/wuttaweb
    api/wuttaweb.app
    api/wuttaweb.auth
+   api/wuttaweb.cli
+   api/wuttaweb.cli.webapp
    api/wuttaweb.conf
    api/wuttaweb.db
    api/wuttaweb.db.continuum
    api/wuttaweb.db.sess
+   api/wuttaweb.emails
    api/wuttaweb.forms
    api/wuttaweb.forms.base
    api/wuttaweb.forms.schema
@@ -51,6 +55,7 @@ the narrative docs are pretty scant.  That will eventually change.
    api/wuttaweb.views.base
    api/wuttaweb.views.batch
    api/wuttaweb.views.common
+   api/wuttaweb.views.email
    api/wuttaweb.views.essential
    api/wuttaweb.views.master
    api/wuttaweb.views.people

wuttaweb-0.19.0/docs/narr/cli/builtin.rst

@@ -0,0 +1,28 @@
+
+===================
+ Built-in Commands
+===================
+
+Below are the :term:`subcommands <subcommand>` which come with
+WuttaWeb.
+
+
+.. _wutta-webapp:
+
+``wutta webapp``
+----------------
+
+Run the web app, according to config file(s).
+
+This command is a convenience only; under the hood it can run `uvicorn
+<https://www.uvicorn.org/#uvicornrun>`_ but by default will run
+whatever :ref:`pserve <pyramid:pserve_script>` is setup to do (which
+usually is `waitress
+<https://docs.pylonsproject.org/projects/waitress/en/latest/index.html>`_).
+
+Ultimately it's all up to config, so run different web apps with
+different config files.
+
+Defined in: :mod:`wuttaweb.cli.webapp`
+
+.. program-output:: wutta webapp --help

wuttaweb-0.19.0/docs/narr/cli/index.rst

@@ -0,0 +1,14 @@
+
+==============
+ Command Line
+==============
+
+There isn't much to the command line for WuttaWeb, but here it is.
+
+For more general info about CLI see
+:doc:`wuttjamaican:narr/cli/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   builtin

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "WuttaWeb"
-version = "0.17.2"
+version = "0.19.0"
 description = "Web App for Wutta Framework"
 readme = "README.md"
 authors = [{name = "Lance Edgar", email = "lance@wuttaproject.org"}]
@@ -30,6 +30,7 @@ classifiers = [
 ]
 requires-python = ">= 3.8"
 dependencies = [
+        "asgiref",
         "ColanderAlchemy",
         "humanize",
         "markdown",
@@ -43,32 +44,32 @@ dependencies = [
         "pyramid_tm",
         "waitress",
         "WebHelpers2",
-        "WuttJamaican[db]>=0.18.0",
+        "WuttJamaican[db]>=0.19.0",
         "zope.sqlalchemy>=1.5",
 ]
 
 
 [project.optional-dependencies]
 continuum = ["Wutta-Continuum"]
-docs = ["Sphinx", "furo"]
+docs = ["Sphinx", "furo", "sphinxcontrib-programoutput"]
 tests = ["pytest-cov", "tox"]
 
 
 [project.entry-points."fanstatic.libraries"]
 wuttaweb_img = "wuttaweb.static:img"
 
-
 [project.entry-points."paste.app_factory"]
 main = "wuttaweb.app:main"
 
-
 [project.entry-points."wutta.app.providers"]
 wuttaweb = "wuttaweb.app:WebAppProvider"
 
-
 [project.entry-points."wutta.config.extensions"]
 wuttaweb = "wuttaweb.conf:WuttaWebConfigExtension"
 
+[project.entry-points."wutta.typer_imports"]
+wuttaweb = "wuttaweb.cli"
+
 
 [project.urls]
 Homepage = "https://wuttaproject.org/"

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/src/wuttaweb/app.py

@@ -24,23 +24,31 @@
 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
 
 
+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.
+    the :term:`app handler`, which are specific to web apps.  It also
+    registers some :term:`email templates <email template>` for the
+    app, etc.
     """
-    email_templates = 'wuttaweb:email/templates'
+    email_modules = ['wuttaweb.emails']
+    email_templates = ['wuttaweb:email-templates']
 
     def get_web_handler(self, **kwargs):
         """
@@ -87,17 +95,20 @@ def make_wutta_config(settings, config_maker=None, **kwargs):
 
     If this config file path cannot be discovered, an error is raised.
     """
-    # 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
+    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'):
@@ -148,19 +159,18 @@ def make_pyramid_config(settings):
 
 def main(global_config, **settings):
     """
-    This function returns a Pyramid WSGI application.
-
-    Typically there is no need to call this function directly, but it
-    may be configured as the web app entry point like so:
-
-    .. code-block:: ini
-
-       [app:main]
-       use = egg:wuttaweb
-
-    The app returned by this function is quite minimal, so most apps
-    will need to define their own ``main()`` function, and use that
-    instead.
+    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)
     pyramid_config = make_pyramid_config(settings)
@@ -170,3 +180,71 @@ def main(global_config, **settings):
     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):
+        make_wsgi_app = app.load_object(main_app)
+    elif callable(main_app):
+        make_wsgi_app = main_app
+    else:
+        raise ValueError("main_app must be spec or callable")
+
+    # construct a pyramid app "per usual"
+    return make_wsgi_app({}, **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)

wuttaweb-0.19.0/src/wuttaweb/cli/__init__.py

@@ -0,0 +1,28 @@
+# -*- 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 - ``wutta`` subcommands
+"""
+
+# nb. must bring in all modules for discovery to work
+from . import webapp

wuttaweb-0.19.0/src/wuttaweb/cli/webapp.py

@@ -0,0 +1,88 @@
+# -*- 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/>.
+#
+################################################################################
+"""
+See also: :ref:`wutta-webapp`
+"""
+
+import os
+import sys
+from typing_extensions import Annotated
+
+import typer
+from pyramid.scripts import pserve
+
+from wuttjamaican.cli import wutta_typer
+
+
+@wutta_typer.command()
+def webapp(
+        ctx: typer.Context,
+        auto_reload: Annotated[
+            bool,
+            typer.Option('--reload', '-r',
+                         help="Auto-reload web app when files change.")] = False,
+):
+    """
+    Run the configured web app
+    """
+    config = ctx.parent.wutta_config
+
+    # we'll need config file(s) to specify for web app
+    if not config.files_read:
+        sys.stderr.write("no config files found!\n")
+        sys.exit(1)
+
+    runner = config.get(f'{config.appname}.web.app.runner', default='pserve')
+    if runner == 'pserve':
+
+        # run pserve
+        argv = ['pserve', f'file+ini:{config.files_read[0]}']
+        if ctx.params['auto_reload']:
+            argv.append('--reload')
+        pserve.main(argv=argv)
+
+    elif runner == 'uvicorn':
+
+        import uvicorn
+
+        # need service details from config
+        spec = config.require(f'{config.appname}.web.app.spec')
+        kw = {
+            'host': config.get(f'{config.appname}.web.app.host', default='127.0.0.1'),
+            'port': config.get_int(f'{config.appname}.web.app.port', default=8000),
+            'reload': ctx.params['auto_reload'],
+            'reload_dirs': config.get_list(f'{config.appname}.web.app.reload_dirs'),
+            'factory': config.get_bool(f'{config.appname}.web.app.factory', default=False),
+            'interface': config.get(f'{config.appname}.web.app.interface', default='auto'),
+        }
+
+        # also must inject our config files to env, since there is no
+        # other way to specify when running via uvicorn
+        os.environ['WUTTA_CONFIG_FILES'] = os.pathsep.join(config.files_read)
+
+        # run uvicorn
+        uvicorn.run(spec, **kw)
+
+    else:
+        sys.stderr.write(f"unknown web app runner: {runner}\n")
+        sys.exit(2)

wuttaweb-0.19.0/src/wuttaweb/emails.py

@@ -0,0 +1,48 @@
+# -*- 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/>.
+#
+################################################################################
+"""
+:term:`Email Settings <email setting>` for WuttaWeb
+"""
+
+from wuttjamaican.email import EmailSetting
+
+
+class feedback(EmailSetting):
+    """
+    Sent when user submits feedback via the web app.
+    """
+    default_subject = "User Feedback"
+
+    def sample_data(self):
+        """ """
+        model = self.app.model
+        person = model.Person(full_name="Barney Rubble")
+        user = model.User(username='barney', person=person)
+        return {
+            'user': user,
+            'user_name': str(person),
+            'user_url': '#',
+            'referrer': 'http://example.com/',
+            'client_ip': '127.0.0.1',
+            'message': "This app is cool but needs a new feature.\n\nAllow me to describe...",
+        }

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/src/wuttaweb/forms/schema.py

@@ -30,9 +30,11 @@ import uuid as _uuid
 import colander
 import sqlalchemy as sa
 
+from wuttjamaican.db.model import Person
+from wuttjamaican.conf import parse_list
+
 from wuttaweb.db import Session
 from wuttaweb.forms import widgets
-from wuttjamaican.db.model import Person
 
 
 class WuttaDateTime(colander.DateTime):
@@ -569,5 +571,36 @@ class FileDownload(colander.String):
         return widgets.FileDownloadWidget(self.request, **kwargs)
 
 
+class EmailRecipients(colander.String):
+    """
+    Custom schema type for :term:`email setting` recipient fields
+    (``To``, ``Cc``, ``Bcc``).
+    """
+
+    def serialize(self, node, appstruct):
+        if appstruct is colander.null:
+            return colander.null
+
+        return '\n'.join(parse_list(appstruct))
+
+    def deserialize(self, node, cstruct):
+        """ """
+        if cstruct is colander.null:
+            return colander.null
+
+        values = [value for value in parse_list(cstruct)
+                  if value]
+        return ', '.join(values)
+
+    def widget_maker(self, **kwargs):
+        """
+        Constructs a default widget for the field.
+
+        :returns: Instance of
+           :class:`~wuttaweb.forms.widgets.EmailRecipientsWidget`.
+        """
+        return widgets.EmailRecipientsWidget(**kwargs)
+
+
 # nb. colanderalchemy schema overrides
 sa.DateTime.__colanderalchemy_config__ = {'typ': WuttaDateTime}

{wuttaweb-0.17.2 → wuttaweb-0.19.0}/src/wuttaweb/forms/widgets.py

@@ -51,6 +51,8 @@ from deform.widget import (Widget, TextInputWidget, TextAreaWidget,
                            DateTimeInputWidget, MoneyInputWidget)
 from webhelpers2.html import HTML
 
+from wuttjamaican.conf import parse_list
+
 from wuttaweb.db import Session
 from wuttaweb.grids import Grid
 
@@ -423,6 +425,41 @@ class PermissionsWidget(WuttaCheckboxChoiceWidget):
         return super().serialize(field, cstruct, **kw)
 
 
+class EmailRecipientsWidget(TextAreaWidget):
+    """
+    Widget for :term:`email setting` recipient fields (``To``, ``Cc``,
+    ``Bcc``).
+
+    This is a subclass of
+    :class:`deform:deform.widget.TextAreaWidget`.  It uses these
+    Deform templates:
+
+    * ``textarea``
+    * ``readonly/email_recips``
+
+    See also the :class:`~wuttaweb.forms.schema.EmailRecipients`
+    schema type, which uses this widget.
+    """
+    readonly_template = 'readonly/email_recips'
+
+    def serialize(self, field, cstruct, **kw):
+        """ """
+        readonly = kw.get('readonly', self.readonly)
+        if readonly:
+            kw['recips'] = parse_list(cstruct or '')
+
+        return super().serialize(field, cstruct, **kw)
+
+    def deserialize(self, field, pstruct):
+        """ """
+        if pstruct is colander.null:
+            return colander.null
+
+        values = [value for value in parse_list(pstruct)
+                  if value]
+        return ', '.join(values)
+
+
 class BatchIdWidget(Widget):
     """
     Widget for use with the