.. default-role:: code
Keg Elements
####################
.. image:: https://circleci.com/gh/level12/keg-elements.svg?style=svg
:target: https://circleci.com/gh/level12/keg-elements
.. image:: https://codecov.io/github/level12/keg-elements/coverage.svg?branch=master
:target: https://codecov.io/github/level12/keg-elements?branch=master
Keg Elements is a collection of helpers and base classes for building apps with
`Keg`_ or Keg extensions.
.. _Keg: https://pypi.python.org/pypi/Keg
A Simple Example
================
For a simple example and a checklist of sorts for app setup, see the
`Getting Started guide <https://keg-elements.readthedocs.io/en/stable/getting-started.html>`_ in the docs.
Development
===========
To develop on this project, begin by running our tests::
git clone https://github.com/level12/keg-elements keg-elements-src
cd keg-elements-src
tox
You can then examine tox.ini for insights into our development process. In particular, we:
* use `py.test` for testing (and coverage analysis)
* use `flake8` for linting
Preview Readme
--------------
When updating the readme, use `restview --long-description` to preview changes.
Pre-commit Hooks
----------------
You should install the pre-commit hooks by running ::
pre-commit install
This will ensure that your code is ready for review.
Issues & Discussion
====================
Please direct questions, comments, bugs, feature requests, etc. to:
https://github.com/level12/keg-elements/issues
Links
=====
* Documentation: https://keg-elements.readthedocs.io/en/stable/index.html
* Releases: https://pypi.org/project/KegElements/
* Code: https://github.com/level12/keg-elements
* Issue tracker: https://github.com/level12/keg-elements/issues
* Keg framework: https://github.com/level12/keg
* Questions & comments: http://groups.google.com/group/blazelibs
Changelog
=========
0.7.2 released 2022-03-04
-------------------------
- adjust form mixin interface to clarify methods related to forms and make overrides easier (2a326b5_)
.. _2a326b5: https://github.com/level12/keg-elements/commit/2a326b5
0.7.1 released 2022-03-04
-------------------------
- add method errors out on invalid field name (9511f73_)
.. _9511f73: https://github.com/level12/keg-elements/commit/9511f73
0.7.0 released 2022-03-04
-------------------------
- add base class/mixin for form views (fcf8f02_)
- multiselect field will not coerce every option to an object, performance issue (0ccd609_)
- edit method errors out on invalid field name (98ad0b0_)
- factor test column data skipping (639bcb8_)
- support SA column properties in test data generation (1148633_)
- support WTForms 3.0.0 with form-level validation errors, field flags changes (794ce75_)
.. _fcf8f02: https://github.com/level12/keg-elements/commit/fcf8f02
.. _0ccd609: https://github.com/level12/keg-elements/commit/0ccd609
.. _98ad0b0: https://github.com/level12/keg-elements/commit/98ad0b0
.. _639bcb8: https://github.com/level12/keg-elements/commit/639bcb8
.. _1148633: https://github.com/level12/keg-elements/commit/1148633
.. _794ce75: https://github.com/level12/keg-elements/commit/794ce75
0.6.0 released 2021-09-10
-------------------------
Note: due to the form field description change listed below, JS popover usage
from the previous UX can be removed from apps.
- Move form field descriptions to be more visible (f7a287e_)
- Resolve jinja2 Markup deprecation (86cfe0e_)
- Adds column check to verify date/time defaults are not set to an instantiated value Fixes #149 (d8489d1_)
- Drop python 3.6 from testing, add 3.9 (93ee3df_)
- Support webgrid form posts in GridView (requires webgrid's form args loader) (b945bb4_)
.. _f7a287e: https://github.com/level12/keg-elements/commit/f7a287e
.. _86cfe0e: https://github.com/level12/keg-elements/commit/86cfe0e
.. _d8489d1: https://github.com/level12/keg-elements/commit/d8489d1
.. _93ee3df: https://github.com/level12/keg-elements/commit/93ee3df
.. _b945bb4: https://github.com/level12/keg-elements/commit/b945bb4
0.5.30 released 2021-02-02
--------------------------
- Add magnitude/range/type directives for random number generation in testing (a9ca44f_)
- Set up documentation on readthedocs.io (f68c812_)
.. _a9ca44f: https://github.com/level12/keg-elements/commit/a9ca44f
.. _f68c812: https://github.com/level12/keg-elements/commit/f68c812
0.5.29 released 2021-01-29
--------------------------
- Add RelationshipField and RelationshipMultipleField for generating select fields from ORM (8d90b5a_)
- Add form meta option include_required_foreign_keys for form generation (8d90b5a_)
- Add standard testing FormBase for field verification (2b0ee8a_)
- Allow model form subclasses to utilize the super's FieldsMeta (84dcc1f_)
- Use blank FieldMeta object by default when no meta is given (2457605_)
- Provide a model mixin for generic id/value lookup tables (a392941_)
- Add testing_set_related entity method to wrap related object creation (e6fe3d9_)
.. _8d90b5a: https://github.com/level12/keg-elements/commit/8d90b5a
.. _2b0ee8a: https://github.com/level12/keg-elements/commit/2b0ee8a
.. _84dcc1f: https://github.com/level12/keg-elements/commit/84dcc1f
.. _2457605: https://github.com/level12/keg-elements/commit/2457605
.. _a392941: https://github.com/level12/keg-elements/commit/a392941
.. _e6fe3d9: https://github.com/level12/keg-elements/commit/e6fe3d9
0.5.28 released 2020-11-13
--------------------------
- Auto-generate form field options for enum columns (a074cd2_)
- Fix mssql CI (4ec0480_)
- Fix test model key cascade (53dd792_)
- Fix update_collection for models with unique constraints (900f3ec_)
.. _a074cd2: https://github.com/level12/keg-elements/commit/a074cd2
.. _4ec0480: https://github.com/level12/keg-elements/commit/4ec0480
.. _53dd792: https://github.com/level12/keg-elements/commit/53dd792
.. _900f3ec: https://github.com/level12/keg-elements/commit/900f3ec
0.5.27 released 2020-06-09
--------------------------
- Properly handle missing or empty config keys in Sentry filtering (bfb413b_)
.. _bfb413b: https://github.com/level12/keg-elements/commit/bfb413b
0.5.26 released 2020-06-09
--------------------------
- Upgrade Sentry library and improve filtering of sensitive data in error reports (5c0afad_)
- Add alembic helper functions for common tasks (9440a4e_)
- Require numeric columns to specify scale and precision (d0e0260_)
- Improve form-level error handling (e590f2d_)
.. _5c0afad: https://github.com/level12/keg-elements/commit/5c0afad
.. _9440a4e: https://github.com/level12/keg-elements/commit/9440a4e
.. _d0e0260: https://github.com/level12/keg-elements/commit/d0e0260
.. _e590f2d: https://github.com/level12/keg-elements/commit/e590f2d
0.5.25 released 2020-05-12
--------------------------
- check translations in CI (3a01a93_)
- add GridView for convenient webgrid usage (a9deb06_)
- support wtforms 2.3+ (0d78557_)
- remove pytest from non-testing code (5e11b79_)
.. _3a01a93: https://github.com/level12/keg-elements/commit/3a01a93
.. _a9deb06: https://github.com/level12/keg-elements/commit/a9deb06
.. _0d78557: https://github.com/level12/keg-elements/commit/0d78557
.. _5e11b79: https://github.com/level12/keg-elements/commit/5e11b79
0.5.24 released 2020-03-23
--------------------------
- select all/none feature for MultiCheckbox fields (vanilla JS) (7a727b6_)
.. _7a727b6: https://github.com/level12/keg-elements/commit/7a727b6
0.5.23 released 2020-03-20
--------------------------
- enable MultiCheckboxField usage in templates for bootstrap 3 (c1dba1b_)
- fix SA arrow column default timezone (3eea89d_)
.. _c1dba1b: https://github.com/level12/keg-elements/commit/c1dba1b
.. _3eea89d: https://github.com/level12/keg-elements/commit/3eea89d
0.5.22 released 2020-02-27
--------------------------
- Add missing class to checkbox input (4b4e44c_)
.. _4b4e44c: https://github.com/level12/keg-elements/commit/4b4e44c
0.5.21 released 2020-02-21
--------------------------
- Add support for multi select checkbox form fields (fa21fa4_)
- allow columns to override their random data generation (a3445c1_)
.. _fa21fa4: https://github.com/level12/keg-elements/commit/fa21fa4
.. _a3445c1: https://github.com/level12/keg-elements/commit/a3445c1
0.5.20 released 2020-02-03
--------------------------
- Fix BS4 Field Description (a9d3479_)
.. _a9d3479: https://github.com/level12/keg-elements/commit/a9d3479
0.5.19 released 2019-11-19
--------------------------
- Adds a U.S. state select field (3abd696_)
- Add type hint widget for use with form text inputs (fe089e0_)
- Use recommended classes and tag layout for rendering bootstrap 4 checkboxes (d20b084_)
- Add Python 3.8 support and drop support for Python 3.5 (d87b2db_)
- Exclude create/update timestamp fields from model form generation by default (012fe38_)
.. _3abd696: https://github.com/level12/keg-elements/commit/3abd696
.. _fe089e0: https://github.com/level12/keg-elements/commit/fe089e0
.. _d20b084: https://github.com/level12/keg-elements/commit/d20b084
.. _d87b2db: https://github.com/level12/keg-elements/commit/d87b2db
.. _012fe38: https://github.com/level12/keg-elements/commit/012fe38
0.5.18 released 2019-08-05
--------------------------
- Prevent double rendering of hidden form inputs in template macros (e0b47dc_)
.. _e0b47dc: https://github.com/level12/keg-elements/commit/e0b47dc
0.5.17 released 2019-07-29
--------------------------
- Skip arrow fields during form generation if default value set (95e26a6_)
- Add bootstrap 4 form template option (bc4efcd_)
.. _95e26a6: https://github.com/level12/keg-elements/commit/95e26a6
.. _bc4efcd: https://github.com/level12/keg-elements/commit/bc4efcd
0.5.16 released 2019-07-09
--------------------------
- db: Add SoftDeleteMixin (ebc25b9_)
- Enable Manual Ordering of Form Fields (#101) (00ce0b6_)
- Merge pull request #103 from level12/pre-commit-hook-setup (68b92d6_)
.. _ebc25b9: https://github.com/level12/keg-elements/commit/ebc25b9
.. _00ce0b6: https://github.com/level12/keg-elements/commit/00ce0b6
.. _68b92d6: https://github.com/level12/keg-elements/commit/68b92d6
0.5.15 released 2019-07-02
--------------------------
- Add base class for enum types used by database entities (49e4cf3_)
- Improve random number generation in testing defaults for numeric columns (25321c1_)
.. _49e4cf3: https://github.com/level12/keg-elements/commit/49e4cf3
.. _25321c1: https://github.com/level12/keg-elements/commit/25321c1
0.5.14 released 2019-06-28
--------------------------
- Add features to form's FieldMeta overrides and improve support for enum columns in model forms (c7ddf0d_)
- Drop 2.7 support and add 3.7 support (c7ddf0d_)
- Fix spelling errors (be0334f_)
.. _c7ddf0d: https://github.com/level12/keg-elements/commit/c7ddf0d
.. _be0334f: https://github.com/level12/keg-elements/commit/be0334f
0.5.13 released 2019-06-17
--------------------------
- Add additional testing helpers and fix float field form generation issue (4b725fd_)
.. _4b725fd: https://github.com/level12/keg-elements/commit/4b725fd
0.5.12 released 2019-02-07
--------------------------
- Fix Deprecation Warnings and Remove Wheelhouse (7af6f55_)
.. _7af6f55: https://github.com/level12/keg-elements/commit/7af6f55
0.5.11 released 2018-11-20
--------------------------
- Switch yield tests to loops to resolve pytest warning (a3e1b5c_)
.. _a3e1b5c: https://github.com/level12/keg-elements/commit/a3e1b5c
0.5.10 released 2018-11-13
--------------------------
- Added template support for adding tab indexes when creating wtforms (f36997e_)
- Add support for multiple-column keys in ColumnCheck (8dc840b_)
- Add optional i18n support using morphi (46229a4_)
.. _f36997e: https://github.com/level12/keg-elements/commit/f36997e
.. _8dc840b: https://github.com/level12/keg-elements/commit/8dc840b
.. _46229a4: https://github.com/level12/keg-elements/commit/46229a4
0.5.9 released 2018-09-19
-------------------------
- FEAT: Add additional metadata to the results of Form.fields_todict (2f863f1_)
.. _2f863f1: https://github.com/level12/keg-elements/commit/2f863f1
0.5.8 released 2018-07-19
-------------------------
- Merge pull request #82 from level12/add-alphanumeric-validator (bbf43ec_)
.. _bbf43ec: https://github.com/level12/keg-elements/commit/bbf43ec
0.5.7 released 2018-06-19
-------------------------
- Merge pull request #80 from level12/check-for-missing-app-ctx (1d0f3d8_)
.. _1d0f3d8: https://github.com/level12/keg-elements/commit/1d0f3d8
0.5.6 released 2018-04-30
-------------------------
- FEAT: Automatically generate range validators for numeric fields in `ModelForm`\ s (48a3827_)
- Improvements to the uniqueness form validator (29937c5_)
.. _48a3827: https://github.com/level12/keg-elements/commit/48a3827
.. _29937c5: https://github.com/level12/keg-elements/commit/29937c5
0.5.5 released 2018-04-25
-------------------------
- FEAT: Add custom Sentry client to filter out flask config object from reports (927e012_)
.. _927e012: https://github.com/level12/keg-elements/commit/927e012
0.5.4 released 2017-08-08
-------------------------
- Use pyp to manage releases (5b11356_)
- FEAT: Add file/stream encryption methods (aeab61a_)
.. _5b11356: https://github.com/level12/keg-elements/commit/5b11356
.. _aeab61a: https://github.com/level12/keg-elements/commit/aeab61a
0.5.3 - 2017-04-26
------------------
* FEAT: Add DontCare for Easy Testing (28643d6_)
.. _28643d6: https://github.com/level12/keg-elements/commit/28643d6
0.5.2 - 2017-03-23
------------------
* FEAT: Add additional utility functions (2e27a60_)
* BUG: Check all records when updating a collection (fffb7c8_)
.. _2e27a60: https://github.com/level12/keg-elements/commit/2e27a60
.. _fffb7c8: https://github.com/level12/keg-elements/commit/fffb7c8
0.5.0 - 2016-12-19
-------------------
* FEAT: Create crypto primitives (5a981b5_)
* Refactor testing_create kwargs validation and ignore "_" prefixed keys (484d032_)
.. _5a981b5: https://github.com/level12/keg-elements/commit/5a981b5
.. _484d032: https://github.com/level12/keg-elements/commit/484d032
0.4.2 - 2016-11-11
------------------
* FEATURE: Verify kwargs correspond to columns and relationships in `testing_create`. (db533dd_)
* FEATURE: Add support for form-level validation. (GH-53_)
.. _db533dd: https://github.com/level12/keg-elements/commit/db533dd
.. _GH-53: https://github.com/level12/keg-elements/pull/53
0.4.1 - 2016-10-19
------------------
* Add unique form validator (a0c7447_)
.. _a0c7447: https://github.com/level12/keg-elements/commit/a0c7447
0.4.0 - 2016-09-08
------------------
* FEATURE: Port ``MethodsMixin`` with a number of helpful functions when working with
SQLAlchemy ORM entities. (GH-49_, GH-51_)
* FEATURE: Add a new TimeZone Column. (GH-50_)
* MAINTENANCE: Provide better testing support for polymorphic SQLAlchemy
ORM entities. (GH-47_)
* BUG: Fix descriptions when implicitly rendering checkboxes (GH-48_)
.. _GH-50: https://github.com/level12/keg-elements/pull/50
.. _GH-51: https://github.com/level12/keg-elements/pull/51
.. _GH-49: https://github.com/level12/keg-elements/pull/49
.. _GH-48: https://github.com/level12/keg-elements/pull/48
.. _GH-47: https://github.com/level12/keg-elements/pull/47
0.3.2 - 2016-08-03
------------------
* Support `dirty_check` flag on form objects (GH-46_)
.. _GH-46: https://github.com/level12/keg-elements/pull/46
0.3.1
------
* Allow FieldMeta to override default widget and add extra validators (GH-38)
* Allow customization of readonly and disabled attributes on input, select, and radio fields (GH-37)
* Improve the logic for when to default a form field to RequiredBoolRadioField (GH-36)
* Upgrades to the CI Environment
0.3.0
-----
* Allow static renders to be configured with custom macros. (GH-34)
* Synchronize static templates with dynamic templates. (GH-31)
* You can now give a field a description with a string or callback. (GH-23, GH-22)
* Introduced a RequiredBoolRadioField for use with boolean columns. (GH-25)
* Support randomly filling EmailTypes. (GH-24)
* Support additional parameters for randomizing integers. (GH-19)
* ``testing_create`` will randomly select a boolean value for SQLAlchemy boolean
fields. (GH-28)
* We now have a working CI. (GH-27)
* Constraint tests will fail if all fields are not covered. (GH-21)
* Introduced a new form-upload macro. (GH-18)
* Static render now uses element.data unless it is a SelectField (GH-16)
* ``MethodsMixin`` has a new ``to_dict`` method. (d83d93f)
* ``MethodsMixin`` has a new ``ensure`` method. (e5687ed)
* Fix bug where static renders would not output the label. (GH-33)
* Fix property names when using automatic test cases. (GH-29)
* Fix issue where we wouldn't use a consistent json parser. (GH-13)
* Fix a bug where polymorphic columns are included in ``testing_create``. (147c23)
development version: 2015-07-28
-------------------------------
* Add db.mixins with DefaultColsMixin (id, Arrow lib UTC timestamps) and MethodsMixin (incomplete).
* Some MethodsMixin methods now have support for commit/flush parameters.
* Add .testing:EntityBase which uses named tuples to declare the checks needed and adds some
additional logic.