WuttaWeb 0.16.1__tar.gz → 0.17.0__tar.gz

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.17.0 (2024-12-15)
+
+### Feat
+
+- add basic support for batch execution
+- add basic support for rows grid for master, batch views
+- add basic master view class for batches
+
+### Fix
+
+- add handling for decimal values and lists, in `make_json_safe()`
+- fix behavior when editing Roles for a User
+- add basic views for raw Permissions
+- improve support for date, datetime fields in grids, forms
+- add way to set field widgets using pseudo-type
+- add support for date, datetime form fields
+- make dropdown widgets as wide as other text fields in main form
+- add fallback instance title
+- display "global" errors at top of form, if present
+- add `make_form()` and `make_grid()` methods on web handler
+- correct "empty option" behavior for `ObjectRef` schema type
+- use fanstatic to serve built-in images by default
+
+## v0.16.2 (2024-12-10)
+
+### Fix
+
+- add `GridWidget` and `form.set_grid()` for convenience
+- add "is false or null" grid filter, for nullable bool columns
+- remove Person column for `Person.users` grid display
+- flatten UUID to str for `make_json_safe()`
+
 ## v0.16.1 (2024-12-08)
 
 ### Fix

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: WuttaWeb
-Version: 0.16.1
+Version: 0.17.0
 Summary: Web App for Wutta Framework
 Project-URL: Homepage, https://wuttaproject.org/
 Project-URL: Repository, https://forgejo.wuttaproject.org/wutta/wuttaweb
@@ -26,6 +26,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Requires-Dist: colanderalchemy
 Requires-Dist: humanize
+Requires-Dist: markdown
 Requires-Dist: paginate
 Requires-Dist: paginate-sqlalchemy
 Requires-Dist: pyramid-beaker
@@ -36,7 +37,7 @@ Requires-Dist: pyramid-tm
 Requires-Dist: pyramid>=2
 Requires-Dist: waitress
 Requires-Dist: webhelpers2
-Requires-Dist: wuttjamaican[db]>=0.17.1
+Requires-Dist: wuttjamaican[db]>=0.18.0
 Requires-Dist: zope-sqlalchemy>=1.5
 Provides-Extra: continuum
 Requires-Dist: wutta-continuum; extra == 'continuum'

wuttaweb-0.17.0/docs/api/wuttaweb.views.batch.rst

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

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/docs/conf.py

@@ -29,9 +29,11 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 intersphinx_mapping = {
     'colander': ('https://docs.pylonsproject.org/projects/colander/en/latest/', None),
     'deform': ('https://docs.pylonsproject.org/projects/deform/en/latest/', None),
+    'fanstatic': ('https://www.fanstatic.org/en/latest/', None),
     'pyramid': ('https://docs.pylonsproject.org/projects/pyramid/en/latest/', None),
     'python': ('https://docs.python.org/3/', None),
     'rattail-manual': ('https://rattailproject.org/docs/rattail-manual/', None),
+    'sqlalchemy': ('http://docs.sqlalchemy.org/en/latest/', None),
     'webhelpers2': ('https://webhelpers2.readthedocs.io/en/latest/', None),
     'wuttjamaican': ('https://rattailproject.org/docs/wuttjamaican/', None),
     'wutta-continuum': ('https://rattailproject.org/docs/wutta-continuum/', None),

wuttaweb-0.17.0/docs/glossary.rst

@@ -0,0 +1,30 @@
+.. _glossary:
+
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   grid
+     This refers to a "table of data, with features" essentially.
+     Sometimes it may be displayed as a simple table with no features,
+     or sometimes it has sortable columns, search filters and other
+     tools.
+
+     See also the :class:`~wuttaweb.grids.base.Grid` base class.
+
+   menu handler
+     This is the :term:`handler` responsible for constructing the main
+     app menu at top of page.
+
+     The menu handler is accessed by way of the :term:`web handler`.
+
+     See also the :class:`~wuttaweb.menus.MenuHandler` base class.
+
+   web handler
+     This is the :term:`handler` responsible for overall web layer
+     customizations, e.g. logo image and menu overrides.  Although
+     the latter it delegates to the :term:`menu handler`.
+
+     See also the :class:`~wuttaweb.handler.WebHandler` base class.

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/docs/index.rst

@@ -49,6 +49,7 @@ the narrative docs are pretty scant.  That will eventually change.
    api/wuttaweb.views
    api/wuttaweb.views.auth
    api/wuttaweb.views.base
+   api/wuttaweb.views.batch
    api/wuttaweb.views.common
    api/wuttaweb.views.essential
    api/wuttaweb.views.master

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "WuttaWeb"
-version = "0.16.1"
+version = "0.17.0"
 description = "Web App for Wutta Framework"
 readme = "README.md"
 authors = [{name = "Lance Edgar", email = "lance@wuttaproject.org"}]
@@ -32,6 +32,7 @@ requires-python = ">= 3.8"
 dependencies = [
         "ColanderAlchemy",
         "humanize",
+        "markdown",
         "paginate",
         "paginate_sqlalchemy",
         "pyramid>=2",
@@ -42,7 +43,7 @@ dependencies = [
         "pyramid_tm",
         "waitress",
         "WebHelpers2",
-        "WuttJamaican[db]>=0.17.1",
+        "WuttJamaican[db]>=0.18.0",
         "zope.sqlalchemy>=1.5",
 ]
 
@@ -53,6 +54,10 @@ docs = ["Sphinx", "furo"]
 tests = ["pytest-cov", "tox"]
 
 
+[project.entry-points."fanstatic.libraries"]
+wuttaweb_img = "wuttaweb.static:img"
+
+
 [project.entry-points."paste.app_factory"]
 main = "wuttaweb.app:main"
 

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/src/wuttaweb/forms/base.py

@@ -27,6 +27,9 @@ Base form classes
 import logging
 from collections import OrderedDict
 
+import sqlalchemy as sa
+from sqlalchemy import orm
+
 import colander
 import deform
 from colanderalchemy import SQLAlchemySchemaNode
@@ -311,6 +314,7 @@ class Form:
                 self.model_class = type(self.model_instance)
 
         self.set_fields(fields or self.get_fields())
+        self.set_default_widgets()
 
         # nb. this tracks grid JSON data for inclusion in page template
         self.grid_vue_context = OrderedDict()
@@ -457,23 +461,122 @@ class Form:
         if self.schema:
             self.schema[key] = node
 
-    def set_widget(self, key, widget):
+    def set_widget(self, key, widget, **kwargs):
         """
         Set/override the widget for a field.
 
+        You can specify a widget instance or else a named "type" of
+        widget, in which case that is passed along to
+        :meth:`make_widget()`.
+
         :param key: Name of field.
 
-        :param widget: Instance of
-           :class:`deform:deform.widget.Widget`.
+        :param widget: Either a :class:`deform:deform.widget.Widget`
+           instance, or else a widget "type" name.
+
+        :param \**kwargs: Any remaining kwargs are passed along to
+           :meth:`make_widget()` - if applicable.
 
         Widget overrides are tracked via :attr:`widgets`.
         """
+        if not isinstance(widget, deform.widget.Widget):
+            widget_obj = self.make_widget(widget, **kwargs)
+            if not widget_obj:
+                raise ValueError(f"widget type not supported: {widget}")
+            widget = widget_obj
+
         self.widgets[key] = widget
 
         # update schema if necessary
         if self.schema and key in self.schema:
             self.schema[key].widget = widget
 
+    def make_widget(self, widget_type, **kwargs):
+        """
+        Make and return a new field widget of the given type.
+
+        This has built-in support for the following types (although
+        subclass can override as needed):
+
+        * ``'notes'`` => :class:`~wuttaweb.forms.widgets.NotesWidget`
+
+        See also :meth:`set_widget()` which may call this method
+        automatically.
+
+        :param widget_type: Which of the above (or custom) widget
+           type to create.
+
+        :param \**kwargs: Remaining kwargs are passed as-is to the
+           widget factory.
+
+        :returns: New widget instance, or ``None`` if e.g. it could
+           not determine how to create the widget.
+        """
+        from wuttaweb.forms import widgets
+
+        if widget_type == 'notes':
+            return widgets.NotesWidget(**kwargs)
+
+    def set_default_widgets(self):
+        """
+        Set default field widgets, where applicable.
+
+        This will add new entries to :attr:`widgets` for columns
+        whose data type implies a default widget should be used.
+        This is generally only possible if :attr:`model_class` is set
+        to a valid SQLAlchemy mapped class.
+
+        As of writing this only looks for
+        :class:`sqlalchemy:sqlalchemy.types.DateTime` fields and if
+        any are found, they are configured to use
+        :class:`~wuttaweb.forms.widgets.WuttaDateTimeWidget()`.
+        """
+        from wuttaweb.forms import widgets
+
+        if not self.model_class:
+            return
+
+        for key in self.fields:
+            if key in self.widgets:
+                continue
+
+            attr = getattr(self.model_class, key, None)
+            if attr:
+                prop = getattr(attr, 'prop', None)
+                if prop and isinstance(prop, orm.ColumnProperty):
+                    column = prop.columns[0]
+                    if isinstance(column.type, sa.DateTime):
+                        # self.set_renderer(key, self.render_datetime)
+                        self.set_widget(key, widgets.WuttaDateTimeWidget(self.request))
+
+    def set_grid(self, key, grid):
+        """
+        Establish a :term:`grid` to be displayed for a field.  This
+        uses a :class:`~wuttaweb.forms.widgets.GridWidget` to wrap the
+        rendered grid.
+
+        :param key: Name of field.
+
+        :param widget: :class:`~wuttaweb.grids.base.Grid` instance,
+           pre-configured and (usually) with data.
+        """
+        from wuttaweb.forms.widgets import GridWidget
+
+        widget = GridWidget(self.request, grid)
+        self.set_widget(key, widget)
+        self.add_grid_vue_context(grid)
+
+    def add_grid_vue_context(self, grid):
+        """ """
+        if not grid.key:
+            raise ValueError("grid must have a key!")
+
+        if grid.key in self.grid_vue_context:
+            log.warning("grid data with key '%s' already registered, "
+                        "but will be replaced", grid.key)
+
+        self.grid_vue_context[grid.key] = grid.get_vue_context()
+
     def set_validator(self, key, validator):
         """
         Set/override the validator for a field, or the form.
@@ -848,17 +951,6 @@ class Form:
         output = render(template, context)
         return HTML.literal(output)
 
-    def add_grid_vue_context(self, grid):
-        """ """
-        if not grid.key:
-            raise ValueError("grid must have a key!")
-
-        if grid.key in self.grid_vue_context:
-            log.warning("grid data with key '%s' already registered, "
-                        "but will be replaced", grid.key)
-
-        self.grid_vue_context[grid.key] = grid.get_vue_context()
-
     def render_vue_field(
             self,
             fieldname,
@@ -1094,6 +1186,32 @@ class Form:
 
         return self.validated
 
+    def has_global_errors(self):
+        """
+        Convenience function to check if the form has any "global"
+        (not field-level) errors.
+
+        See also :meth:`get_global_errors()`.
+
+        :returns: ``True`` if global errors present, else ``False``.
+        """
+        dform = self.get_deform()
+        return bool(dform.error)
+
+    def get_global_errors(self):
+        """
+        Returns a list of "global" (not field-level) error messages
+        for the form.
+
+        See also :meth:`has_global_errors()`.
+
+        :returns: List of error messages (possibly empty).
+        """
+        dform = self.get_deform()
+        if dform.error is None:
+            return []
+        return dform.error.messages()
+
     def get_field_errors(self, field):
         """
         Return a list of error messages for the given field.

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/src/wuttaweb/forms/schema.py

@@ -24,15 +24,48 @@
 Form schema types
 """
 
+import datetime
 import uuid as _uuid
 
 import colander
+import sqlalchemy as sa
 
 from wuttaweb.db import Session
 from wuttaweb.forms import widgets
 from wuttjamaican.db.model import Person
 
 
+class WuttaDateTime(colander.DateTime):
+    """
+    Custom schema type for ``datetime`` fields.
+
+    This should be used automatically for
+    :class:`sqlalchemy:sqlalchemy.types.DateTime` columns unless you
+    register another default.
+
+    This schema type exists for sake of convenience, when working with
+    the Buefy datepicker + timepicker widgets.
+    """
+
+    def deserialize(self, node, cstruct):
+        """ """
+        if not cstruct:
+            return colander.null
+
+        formats = [
+            '%Y-%m-%dT%H:%M:%S',
+            '%Y-%m-%dT%I:%M %p',
+        ]
+
+        for fmt in formats:
+            try:
+                return datetime.datetime.strptime(cstruct, fmt)
+            except:
+                pass
+
+        node.raise_invalid("Invalid date and/or time")
+
+
 class ObjectNode(colander.SchemaNode):
     """
     Custom schema node class which adds methods for compatibility with
@@ -207,6 +240,11 @@ class ObjectRef(colander.SchemaType):
 
     def serialize(self, node, appstruct):
         """ """
+        # nb. normalize to empty option if no object ref, so that
+        # works as expected
+        if self.empty_option and not appstruct:
+            return self.empty_option[0]
+
         if appstruct is colander.null:
             return colander.null
 
@@ -214,7 +252,7 @@ class ObjectRef(colander.SchemaType):
         node.model_instance = appstruct
 
         # serialize to uuid
-        return appstruct.uuid
+        return appstruct.uuid.hex
 
     def deserialize(self, node, cstruct):
         """ """
@@ -296,7 +334,7 @@ class ObjectRef(colander.SchemaType):
         if 'values' not in kwargs:
             query = self.get_query()
             objects = query.all()
-            values = [(obj.uuid, str(obj))
+            values = [(obj.uuid.hex, str(obj))
                       for obj in objects]
             if self.empty_option:
                 values.insert(0, self.empty_option)
@@ -344,6 +382,30 @@ class PersonRef(ObjectRef):
         return self.request.route_url('people.view', uuid=person.uuid)
 
 
+class RoleRef(ObjectRef):
+    """
+    Custom schema type for a
+    :class:`~wuttjamaican:wuttjamaican.db.model.auth.Role` reference
+    field.
+
+    This is a subclass of :class:`ObjectRef`.
+    """
+
+    @property
+    def model_class(self):
+        """ """
+        model = self.app.model
+        return model.Role
+
+    def sort_query(self, query):
+        """ """
+        return query.order_by(self.model_class.name)
+
+    def get_object_url(self, role):
+        """ """
+        return self.request.route_url('roles.view', uuid=role.uuid)
+
+
 class UserRef(ObjectRef):
     """
     Custom schema type for a
@@ -391,16 +453,24 @@ class RoleRefs(WuttaSet):
         if 'values' not in kwargs:
             model = self.app.model
             auth = self.app.get_auth_handler()
+
+            # avoid built-ins which cannot be assigned to users
             avoid = {
                 auth.get_role_authenticated(self.session),
                 auth.get_role_anonymous(self.session),
             }
             avoid = set([role.uuid for role in avoid])
+
+            # also avoid admin unless current user is root
+            if not self.request.is_root:
+                avoid.add(auth.get_role_administrator(self.session).uuid)
+
+            # everything else can be (un)assigned for users
             roles = self.session.query(model.Role)\
                                 .filter(~model.Role.uuid.in_(avoid))\
                                 .order_by(model.Role.name)\
                                 .all()
-            values = [(role.uuid, role.name) for role in roles]
+            values = [(role.uuid.hex, role.name) for role in roles]
             kwargs['values'] = values
 
         return widgets.RoleRefsWidget(self.request, **kwargs)
@@ -497,3 +567,7 @@ class FileDownload(colander.String):
         """ """
         kwargs.setdefault('url', self.url)
         return widgets.FileDownloadWidget(self.request, **kwargs)
+
+
+# nb. colanderalchemy schema overrides
+sa.DateTime.__colanderalchemy_config__ = {'typ': WuttaDateTime}

{wuttaweb-0.16.1 → wuttaweb-0.17.0}/src/wuttaweb/forms/widgets.py

@@ -36,9 +36,11 @@ in the namespace:
 * :class:`deform:deform.widget.CheckboxWidget`
 * :class:`deform:deform.widget.SelectWidget`
 * :class:`deform:deform.widget.CheckboxChoiceWidget`
+* :class:`deform:deform.widget.DateTimeInputWidget`
 * :class:`deform:deform.widget.MoneyInputWidget`
 """
 
+import datetime
 import os
 
 import colander
@@ -46,7 +48,7 @@ import humanize
 from deform.widget import (Widget, TextInputWidget, TextAreaWidget,
                            PasswordWidget, CheckedPasswordWidget,
                            CheckboxWidget, SelectWidget, CheckboxChoiceWidget,
-                           MoneyInputWidget)
+                           DateTimeInputWidget, MoneyInputWidget)
 from webhelpers2.html import HTML
 
 from wuttaweb.db import Session
@@ -102,7 +104,7 @@ class ObjectRefWidget(SelectWidget):
         # add url, only if rendering readonly
         readonly = kw.get('readonly', self.readonly)
         if readonly:
-            if 'url' not in values and self.url and field.schema.model_instance:
+            if 'url' not in values and self.url and getattr(field.schema, 'model_instance', None):
                 values['url'] = self.url(field.schema.model_instance)
 
         return values
@@ -153,6 +155,43 @@ class WuttaCheckboxChoiceWidget(CheckboxChoiceWidget):
         self.session = session or Session()
 
 
+class WuttaDateTimeWidget(DateTimeInputWidget):
+    """
+    Custom widget for :class:`python:datetime.datetime` fields.
+
+    The main purpose of this widget is to leverage
+    :meth:`~wuttjamaican:wuttjamaican.app.AppHandler.render_datetime()`
+    for the readonly display.
+
+    It is automatically used for SQLAlchemy mapped classes where the
+    field maps to a :class:`sqlalchemy:sqlalchemy.types.DateTime`
+    column.  For other (non-mapped) datetime fields, you may have to
+    use it explicitly via
+    :meth:`~wuttaweb.forms.base.Form.set_widget()`.
+
+    This is a subclass of
+    :class:`deform:deform.widget.DateTimeInputWidget` and uses these
+    Deform templates:
+
+    * ``datetimeinput``
+    """
+
+    def __init__(self, request, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.request = request
+        self.config = self.request.wutta_config
+        self.app = self.config.get_app()
+
+    def serialize(self, field, cstruct, **kw):
+        """ """
+        readonly = kw.get('readonly', self.readonly)
+        if readonly and cstruct:
+            dt = datetime.datetime.fromisoformat(cstruct)
+            return self.app.render_datetime(dt)
+
+        return super().serialize(field, cstruct, **kw)
+
+
 class FileDownloadWidget(Widget):
     """
     Widget for use with :class:`~wuttaweb.forms.schema.FileDownload`
@@ -210,6 +249,44 @@ class FileDownloadWidget(Widget):
         return humanize.naturalsize(size)
 
 
+class GridWidget(Widget):
+    """
+    Widget for fields whose data is represented by a :term:`grid`.
+
+    This is a subclass of :class:`deform:deform.widget.Widget` but
+    does not use any Deform templates.
+
+    This widget only supports "readonly" mode, is not editable.  It is
+    merely a convenience around the grid itself, which does the heavy
+    lifting.
+
+    Instead of creating this widget directly you probably should call
+    :meth:`~wuttaweb.forms.base.Form.set_grid()` on your form.
+
+    :param request: Current :term:`request` object.
+
+    :param grid: :class:`~wuttaweb.grids.base.Grid` instance, used to
+       display the field data.
+    """
+
+    def __init__(self, request, grid, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.request = request
+        self.grid = grid
+
+    def serialize(self, field, cstruct, **kw):
+        """
+        This widget simply calls
+        :meth:`~wuttaweb.grids.base.Grid.render_table_element()` on
+        the ``grid`` to serialize.
+        """
+        readonly = kw.get('readonly', self.readonly)
+        if not readonly:
+            raise NotImplementedError("edit not allowed for this widget")
+
+        return self.grid.render_table_element()
+
+
 class RoleRefsWidget(WuttaCheckboxChoiceWidget):
     """
     Widget for use with User
@@ -280,7 +357,7 @@ class UserRefsWidget(WuttaCheckboxChoiceWidget):
             raise NotImplementedError("edit not allowed for this widget")
 
         model = self.app.model
-        columns = ['person', 'username', 'active']
+        columns = ['username', 'active']
 
         # generate data set for users
         users = []
@@ -344,3 +421,22 @@ class PermissionsWidget(WuttaCheckboxChoiceWidget):
             kw['values'] = values
 
         return super().serialize(field, cstruct, **kw)
+
+
+class BatchIdWidget(Widget):
+    """
+    Widget for use with the
+    :attr:`~wuttjamaican:wuttjamaican.db.model.batch.BatchMixin.id`
+    field of a :term:`batch` model.
+
+    This widget is "always" read-only and renders the Batch ID as
+    zero-padded 8-char string
+    """
+
+    def serialize(self, field, cstruct, **kw):
+        """ """
+        if cstruct is colander.null:
+            return colander.null
+
+        batch_id = int(cstruct)
+        return f'{batch_id:08d}'