WebGrid 0.5.10

A library for rendering HTML tables and Excel files from SQLAlchemy models.

Introduction

WebGrid is a datagrid library for Flask and other Python web frameworks designed to work with SQLAlchemy ORM entities and queries.

With a grid configured from one or more entities, WebGrid provides these features for reporting:

• Automated SQL query construction based on specified columns and query join/filter/sort options

• Renderers to various targets/formats

  • HTML output paired with JS (jQuery) for dynamic features

  • Excel (XLSX)

  • CSV

• User-controlled data filters

  • Per-column selection of filter operator and value(s)

  • Generic single-entry search

• Session storage/retrieval of selected filter options, sorting, and paging

Installation

Install using pip:

pip install webgrid

Some basic internationalization features are available via extra requirements:

pip install webgrid[i18n]

A Simple Example

For a simple example, see the Getting Started guide in the docs.

Running the Tests

Webgrid uses Tox to manage testing environments & initiate tests. Once you have installed it via pip install tox you can run tox to kick off the test suite.

Webgrid is continuously tested against Python 3.6, 3.7, and 3.8. You can test against only a certain version by running tox -e py38-base for whichever Python version you are testing.

Links

• Documentation: https://webgrid.readthedocs.io/en/stable/index.html

• Releases: https://pypi.org/project/WebGrid/

• Code: https://github.com/level12/webgrid

• Issue tracker: https://github.com/level12/webgrid/issues

• Questions & comments: http://groups.google.com/group/blazelibs

Changelog

0.5.10 released 2024-07-19

• ensure session override args replace arg lists (a7c61f6)

• prevent session override from persisting in header form requests (cd1f7cd)

• modernize tested python versions (3557f44)

0.5.9 released 2023-12-08

• ensure query string is applied for testing methods (3ccfb70)

0.5.8 released 2023-11-10

• support werkzeug 3 (857eb32)

0.5.7 released 2023-05-15

• fix OneOf validator exception (3b53cb4)

0.5.6 released 2023-05-12

• fix options validator instance (400288b)

0.5.5 released 2023-05-12

• drop formencode dependency in favor of internal validation (9575f12)

0.5.4 released 2023-05-08

• match datetime filter granularity to filter input (029d7e3)

0.5.3 released 2023-03-02

• fix column attribute extraction for non-SQLAlchemy records (a090491)

0.5.2 released 2023-02-24

• fix openpyxl typing imports when openpyxl not present (d301658)

• SQLAlchemy 2.0 compatibility (no breaking change, retains support for SA 1.4) (bfedc8d)

0.5.1 released 2023-01-20

• add date filter options for last week, past, and future (6a6eccc)

0.5.0 released 2023-01-20

• support openpyxl for XLSX render (in addition to xlsxwriter) (417c75a)

• remove deprecated XLS render (85e6bb9)

• don’t require passing SA column to filter when providing defaults (e0fbc0f)

0.4.13 released 2022-12-12

• better namespacing of datetime filter control JS (e884310)

0.4.12 released 2022-11-07

• handle Decimal type more cleanly when rendering JSON (f8ea07d)

0.4.11 released 2022-10-18

• further clarity on args loaders, the order they run, how results are chained, etc. (9b89854)

• enable grid to build a query string from attributes (400967d)

• provide totals in rendered JSON output (20fe558)

• update dataclass type documentation for usage of JSON grid i/o (35ae887)

• clarify args loader documentation (7ab8d57)

0.4.10 released 2022-08-15

• prevent count queries from re-executing due to sort/page options (0cf55e6)

0.4.9 released 2022-07-25

• add a shortcut route to report grid count without other info (9d9a973)

0.4.8 released 2022-03-08

• allow jinja_loader to be loaded at runtime (4851cc7)

0.4.7 released 2021-12-06

• add query_select_from grid attribute (56425a6)

0.4.6 released 2021-11-17

• provide all column labels in JSON render (ab28bfe)

0.4.5 released 2021-11-11

• fix array enum filter search expression for empty sets (39bfc1a)

0.4.4 released 2021-11-10

• bug fix in option array enum filter (4f09060)

0.4.3 released 2021-11-10

• support array type in test query building (13be909)

• add an enum filter that supports PG array type (faa2e64)

• support html input type designation for JSON on all filters (f60efac)

0.4.2 released 2021-09-30

• support additional types for query-to-string (e76b7e0)

0.4.1 released 2021-09-22

• include HTML field types in serialized filter spec output (e130489)

• add column type helpers to JSON definition (a255035)

• ensure paging defaults are followed if not set in args (2834a23)

• handle None search value coming from args (84c4af5)

• allow columns to be dropped from a grid instance (195942a)

• add sortable column key list to JSON render grid spec (deb5f6b)

• API: add post-init setup hook (56b4e96)

0.4.0 released 2021-09-10

• Use HTML5 date/time input types for filters (76f74b9)

• Support arrow-type columns with date filter (2eedfdc)

• Allow enum filter type to be set on filter class (e0a3ac2)

• Allow adding columns on grid instance (84bbee3)

• Allow columns to be reordered by given keys (affcb54)

• Ensure columns get keyed with their unique names (7549824)

• Clean up search value handling (426ee92)

• Warn developer of openpyxl requirement for xlsx testing (2c6613d)

• Resolve werkzeug Href deprecation (1dc5688)

• Resolve flask attachment_name deprecation (f2e6931)

• Set header action to post/get depending on manager args loaders (45cbb69)

• Fix args loader session key handling (f7b40c6)

• Set request context in testing GridBase as needed (e55979b)

• Add JSON renderer and flask API (274b6bc)

• Made compatible with sqlalchemy 1.4

• Dropped python 3.6 tests, added 3.9

• Removed blazeweb tests due to incompatibility with sqlalchemy 1.4

0.3.7 released 2021-02-16

• enhance performance by compiling jinja template strings once per renderer instance (d8815ea)

0.3.6 released 2021-02-15

• Fix reset arg inclusion in grid url (2064aa8)

0.3.5 released 2021-02-01

• Update readme to point at documentation (083df65)

• Fix imports in testing helpers (dcc96c9)

0.3.4 released 2021-01-25

• Move request/session args loading to manager, prevent cookie overflow (9b4b39e)

• Shift deprecated raises decorator usage to pytest.raises (42cf416)

• Remove unused code objects/attributes (f6e2160)

0.3.3 released 2020-12-10

• Exclude aggregate filters from search unless all are aggregate (8381960)

• Set 2-part filter values next to each other (0ef2a99)

0.3.2 released 2020-11-18

• remove werkzeug version pin (8082a46)

0.3.1 released 2020-11-13

• Fix single-search from aggregate filters (33d772e)

0.3.0 released 2020-11-04

• Set up documentation for use on readthedocs.io (d0a486b)

• Move Add Filter select to top, combine with search row when applicable (4e0a502)

• Create documentation with sphinx (6dbe96a)

• Use openpyxl for testing XLSX output (xlrd is deprecated) (51bc80f)

• Add helper classes for testing grids (3d5867f)

• Run test suite against multiple databases (SQLite, PostgreSQL, MSSQL) (69ce644)

• Assign unique keys when multiple columns have the same name (d34fc89)

• Reduce clicks required to add a filter (c76320f)

• Reduce vertical spacing used in the hader (54f8eb9)

• Deprecate the XLS renderer (6e450f1)

• Clarify removal of python 3.5 support (2f58762)

• Pass all filter values through grid set_filter method (af06abe)

• Add between ops to numeric filters (7736069)

• Ensure grid reset clears search value (b8012d2)

0.2.13 released 2020-07-21

• Fix multiselect filter rendering bug for selected enum options (5e9aa00)

0.2.12 released 2020-07-08

• Fix multiselect filter rendering bug for list options (abfd32f)

0.2.11 released 2020-07-07

• Fix date filter overflow error (116447b)

• Switch test runner to pytest from nose (dfdb3b0)

0.2.10 released 2020-05-15

• simplify page selection to use input instead of select (900abdd)

• remove webhelpers2 usage in favor of inline jinja template strings (0d27fec)

• change date filter “less than days ago” to include today (2e67da0)

• allow custom CSV date formatting (1fb7d03)

• provide query prep by grid configuration (77f68df)

• verify i18n translations in CI and add helper for development (75c0ec0)

0.2.9 released 2020-04-09

• Allow columns to be grouped in the UI with an additional header (HTML, XLSX targets) (3a9e64a)

• Fix bug clearing single filter when sessions are enabled (c14c708)

0.2.8 released 2020-03-20

• fix session persistence for flask (5ed62b8)

0.2.7 released 2020-02-10

• fix issue searching date(time) fields for values that are out of bounds (3d33663)

0.2.6 released 2020-01-14

• fix DateFilter/DateTimeFilter default op bugs introduced in 0.2.5 (edeb74e)

0.2.5 released 2020-01-10

• reduce code complexity (e588630)

• handle missing filter values for DateFilter an DateTimeFilter (b0e614b)

• note: this release has some bugs in DateFilter/DateTimeFilter for handling default op

0.2.4 released 2019-12-06

• split filter key matching for search to a separate method for easier override (95032d2)

• fix DateTimeFilter between operation when missing second operand (acfc86b)

0.2.3 released 2019-11-27

• resolve bad option in multiselect filters (36fc18c)

0.2.2 released 2019-11-26

• improve multiselect filter UI performance for large data sets (8b4fde7)

0.2.1 released 2019-11-07

• layout fix for the search box in the filter block (71c5d56)

0.2.0 released 2019-11-06

• Add generic search box (turned on via enable_search) to search on filtered columns (3624b78)

• Add visible boolean parameter on Column, allow that and render_in to support lambdas for evaluation at run time (0e3e125)

• Fixed pagination styling (b16ddbf)

• Turn multiselect UI on for applicable filters (b7744e7)

• Resolved some deprecation warnings (104a865)

• Added debug logging of queries to aid in profiling (d6eae60)

• Updated pypi license declaraton to use SPDX identifier in the license field (cf59e68)

• Added BSD 3-Clause license (fb4184d)

0.1.45 released 2019-09-04

• Merge pull request #59 from level12/20-allow-list-render-in (e2a5e46)

• Merge pull request #64 from level12/40-cleanup-url-filters (a269e1c)

0.1.44 released 2019-06-27

• Add column and filter classes to support enum types (#60) (9838669)

0.1.43 released 2019-05-20

• fix BC case for session load when the key loads no data (7e11993)

0.1.42 released 2019-05-13

• Ensure session store maintains proper data type through load/save (#35) (e7c5bdf)

• Known issues: backwards-compatibility error when session store has no data

0.1.41 released 2019-03-25

• Fix warning from xlsxwriter when second column has a subtotal (05e0663)

0.1.40 released 2019-02-18

• py3: Fix Deprecation Warning for Inspect Call (#53) (9c87cc4)

0.1.39 released 2019-01-03

• Properly handle None in date filter “between” ops (4da6069)

0.1.38 released 2018-11-14

• Add optional i18n support using morphi (3627e8f) NOTE: there is a slight change that could result in a behavioral change during upgrade! Please see the ‘Upgrading’ section in the readme for more information!

0.1.37 released 2018-09-10

• XLSX formats are cached for performance

0.1.36 released 2018-08-09

• Add test helper assert_rendered_xls_matches in webgrid.testing

• Add support for XLSX, and CSV renderers - If you have xlsxwriter installed, xlsx export link will appear

• DEPRECATED old export mechanism - If you are calling g.xls.as_response() please replace that with g.export_as_response() which will select the correct renderer and return the response correctly - If xlsx is enabled you will need to make this above change to enable xlsx exporting

0.1.35 released 2018-01-05

• fix CSS collision in tr classes with Bootstrap

• change multiselect to use body as the container for the multiselect list

0.1.34 released 2017-08-25

• session_override GET arg added to allow patching additional operators into the session (rather than overriding session filters)

0.1.33 released 2017-06-13

• limit XLS sheet names to 30 characters, per the Excel format limit

0.1.32 released 2017-06-09

• corrected the results of Filter.is_active to account for default operation with no value

• fixed formencode requirement for python 3

• update options filter error to include class name

0.1.31 released 2016-11-03

• corrected DateTimeFilter processing to avoid “invalid date” messages

0.1.30 released 2016-10-28

• fixed problem with lambda default args being processed by the grid

0.1.29 released 2016-10-28

• allow default operation passed to filter to be a callable

0.1.28 released 2016-10-13

• fixed an additional regression in DateFilter and DateTimeFilter validation

0.1.27 released 2016-10-13

• corrected DateFilter and DateTimeFilter operations for empty, not empty, and between

0.1.26 released 2016-10-03

• update TextFilter to support case-insensitive operations for dialects like postgresql and sqlite

0.1.25 released 2016-09-12

• various bug fixes in DateTimeFilter

• introduce support for Arrow date objects in grid and date filters

0.1.24 released 2016-05-10

• enhanced options for subtotals to include sum, avg, strings, and SQLAlchemy expressions

0.1.23 released 2016-04-18

• change dependency to webhelpers2 from webhelpers

• update to support new python-dateutil, including fix of old parsing exception

• fix testing compatibility with Flask-SQLALchemy 2.1

• fix testing dependencies problem in setup

• support Python 3.4 and newer

0.1.22 released 2016-02-18

• fix potential warnings for SQLAlchemy when sorting by a label instead of an SA expression

0.1.21 released 2016-02-18

• bad release

0.1.20 released 2016-02-18

• errant release, identical to 0.1.19

0.1.19 released 2016-02-16

• fix edit/delete link display on large screens

0.1.18 released 2015-12-11

• fix bugs related to default operations using no-input date filters

0.1.17 released 2015-12-04

• add YesNoFilter and OptionsIntFilterBase helper

• fix compatibility with SQLAlchemy 1.0.9 for tests to pass

• add additional DateFilter operators

0.1.16 released 2015-10-15

• fixed problem with possible date/datetime filter overflows

0.1.15 released 2015-07-02

• add time column and filter

0.1.14 released 2015-05-11

• fix problem where empty strings passed to set as a non-required value 2 causes validation error

0.1.13 released 2015-02-12

• attempt to use column label for subtotaling if no SA expression is provided

• allow callers to specify default arguments to filters

0.1.12 released 2014-11-18

• allow filters to set additional html attributes on their table rows

0.1.11 released 2014-10-09

• fixed setup to include only webgrid in install, without the test apps

0.1.10 released 2014-10-02

• bug fix: hide_controls_box grid attribute used in rendering

0.1.9 released 2014-09-22

• bug fix: corrected default_op processing on TextFilter

0.1.8 released 2014-09-22

• enable default_op processing for all filter types

0.1.7 released 2014-09-18

• BC break: replaced MultiSelect widget with multipleSelect plugin. Related JS and CSS must be included (available in webgrid static)

• included missing images referenced by webgrid CSS

0.1.6 released 2014-08-22

• updated filter tests to work with SA0.9

• refactoring related to subtotaling feature

• adjustments for SQLAlchemy 0.9+ (we now support 0.8+)

• workaround for dateutils parsing bug

• testing fixes

• completed dev requirements list

• fixed nose plugin bug, must not assume pathname case consistency (Windows)

• added BlazeWeb adapter

• xls_as_response now an adapter method, called by XLS renderer

• render_template now an optional adapter method, falls back to Jinja2 call

0.1.5 released 2014-05-20

• fix nose plugin setup to avoid warning message

• fix javascript bug related to sorting & newer jQuery libraries

• fix SA expression test to avoid boolean ambiguity

• avoid accidental unicode to text conversion in filters

0.1.4 released 2014-05-18

• fix string/unicode handling to avoid coercion of unicode to ascii

0.1.3 released 2014-05-18

• adjust the way the Flask blueprint is created and registered

• adjust route on blueprint so it has /static/… prefix for URL

0.1.0 - 0.1.2 released 2014-05-17

• initial release

• fix packaging issues (0.1.1)

• adjust init so xlwt not required if not used