|pypi| |actions| |codecov| |downloads|
edc-form-runners
----------------
Classes to manually run modelform validation for clinicedc/edc projects.
The ``FormRunner`` class
++++++++++++++++++++++++
You can use the ``FormRunner`` to rerun modelform validation on all instances of a model.
For example:
.. code-block:: python
runner = FormRunner("intecomm_subject.vitals")
runner.run_all()
This re-runs ``form.is_valid()`` for all instances of ``intecomm_subject.vitals``.
If the Vitals ``ModelForm`` does not validate, the ``FormRunner`` stores each error
of the ``form.errors`` dictionary in model ``Issue`` where
one instance of ``Issue`` is created per field_name:error_message pair.
`Note: Your model must be registered with Admin.`
``run_form_runners``
++++++++++++++++++++
You can run a ``FormRunner`` for every CRF/Requisition model in a module:
.. code-block:: python
from django.apps import apps as django_apps
from edc_form_runners.run_form_runners import run_form_runners
run_form_runners(app_labels=["intecomm_subject"])
or just list a few models explicitly:
.. code-block:: python
from django.apps import apps as django_apps
from edc_form_runners.run_form_runners import run_form_runners
run_form_runners(model_names=["intecomm_subject.vitals", "intecomm_subject.medications"])
Custom FormRunners
++++++++++++++++++
You may wish to ignore some errors; that is, prevent ``FormRunner`` from creating an ``Issue`` instance
for specific fields that do not validate. To do this create a custom ``FormRunner`` for your model
and list the field names to exclude:
.. code-block:: python
class HtnMedicationAdherenceFormRunner(FormRunner):
model_name = "intecomm_subject.htnmedicationadherence"
exclude_formfields = ["pill_count"]
Now you can use the custom ``FormRunner``:
.. code-block:: python
runner = HtnMedicationAdherenceFormRunner()
runner.run_all()
if field ``pill_count`` does not validate, the error message will not be written to the ``Issues`` table.
Registering Custom FormRunners
++++++++++++++++++++++++++++++
A custom ``FormRunner`` must be registered to be used by ``edc_form_runners``.
Declare your custom ``FormRunnners`` in module ``form_runners.py`` in the root of your app:
.. code-block:: python
# form_runners.py
from edc_form_runners.decorators import register
from edc_form_runners.form_runner import FormRunner
@register
class HtnMedicationAdherenceFormRunner(FormRunner):
model_name = "intecomm_subject.htnmedicationadherence"
exclude_formfields = ["pill_count"]
@register
class DmMedicationAdherenceFormRunner(FormRunner):
model_name = "intecomm_subject.dmmedicationadherence"
exclude_formfields = ["pill_count"]
The ``register`` decorator registers the custom classes with ``site_form_runners``.
``get_form_runner``
+++++++++++++++++++
``edc_form_runners`` gets ``FormRunners`` using ``get_form_runner``.
Given a model name in ``label_lower`` format, ``get_form_runner`` checks the site global (``site_form_runners``) and returns
a custom ``FormRunner``, if it exists, otherwise returns the default ``FormRunner``.
In your code you should use ``get_form_runner``:
.. code-block:: python
# good, returned DmMedicationAdherenceFormRunner instead of the default FormRunner
runner = get_form_runner("intecomm_subject.dmmedicationadherence")
runner.run()
# works but does not use your custom form runner
runner = FormRunner("intecomm_subject.dmmedicationadherence")
runner.run_all()
Management Command ``run_form_runners``
+++++++++++++++++++++++++++++++++++++++
You can use the management command ``run_form_runners`` to run form runners for some or
all CRF/Requisitions. Run this command to initially populate ``Issue`` table and whenever you
change validation logic for a form.
Pass the management command one or more app_labels separated by comma:
.. code-block:: bash
>>> python manage.py run_form_runners -a intecomm_subject
or pass one or more model names (label_lower format) separated by comma:
.. code-block:: bash
>>> python manage.py run_form_runners -m intecomm_subject.vitals,intecomm_subject.dmmedicationadherence
You can skip a model as well:
.. code-block:: bash
>>> python manage.py run_form_runners -a intecomm_subject -s intecomm_subject.medicationadherence
``Issue`` ChangeList
++++++++++++++++++++
The ``ChangeList`` for the ``Issue model`` is available in ``edc_data_manager`` and ``edc_form_runners``.
You would typically use the one in ``edc_data_manager``.
From the change list you can:
* search, filter and re-order
* refresh selected ``Issue`` instances from the action menu.
* navigate to a subject`s dashboard
Integrated with the Subject Dashboard
+++++++++++++++++++++++++++++++++++++
The subject dashboard shows an "Issues" badge next to a CRF or Requisition if one exists. You can
hover over the badge to see some of the error messages detected when the ``FormRunner`` last ran.
If a user edits a CRF with a detected issue and the corrected form validates withour error, the
``Issue`` instance is deleted and the badge is no longer displayed.
(See also ``signals.py``)
``FormRunner`` is ``clinicedc`` specific
++++++++++++++++++++++++++++++++++++++++
At the moment, the ``FormRunner`` class is currently ``clinicedc`` specific in that it only works for models with a
``subject_identifier`` or related_visit FK (e.g. ``subject_visit``).
The ``post_save`` signal that updates Issues listens for ``clinicedc`` CRFs and Requisitions by testing if the model instance
is an instance of ``CrfModelMixin``, ``CrfNoManagerModelMixin`` or ``RequisitionModelMixin``.
.. |pypi| image:: https://img.shields.io/pypi/v/edc-form-runners.svg
:target: https://pypi.python.org/pypi/edc-form-runners
.. |actions| image:: https://github.com/clinicedc/edc-form-runners/actions/workflows/build.yml/badge.svg
:target: https://github.com/clinicedc/edc-form-runners/actions/workflows/build.yml
.. |codecov| image:: https://codecov.io/gh/clinicedc/edc-form-runners/branch/develop/graph/badge.svg
:target: https://codecov.io/gh/clinicedc/edc-form-runners
.. |downloads| image:: https://pepy.tech/badge/edc-form-runners
:target: https://pepy.tech/project/edc-form-runners
Raw data
{
"_id": null,
"home_page": "https://github.com/clinicedc/edc-form-runners",
"name": "edc-form-runners",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "django Edc, modelform, validation, clinicedc, clinical trials",
"author": "Erik van Widenfelt",
"author_email": "ew2789@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6f/a1/725f02fcdf2f35667aae571c2efd735efc5d3d8815cc27ce53d7fbc8b2ad/edc-form-runners-0.3.10.tar.gz",
"platform": null,
"description": "|pypi| |actions| |codecov| |downloads|\n\nedc-form-runners\n----------------\n\nClasses to manually run modelform validation for clinicedc/edc projects.\n\n\nThe ``FormRunner`` class\n++++++++++++++++++++++++\n\nYou can use the ``FormRunner`` to rerun modelform validation on all instances of a model.\n\nFor example:\n\n.. code-block:: python\n\n runner = FormRunner(\"intecomm_subject.vitals\")\n runner.run_all()\n\nThis re-runs ``form.is_valid()`` for all instances of ``intecomm_subject.vitals``.\nIf the Vitals ``ModelForm`` does not validate, the ``FormRunner`` stores each error\nof the ``form.errors`` dictionary in model ``Issue`` where\none instance of ``Issue`` is created per field_name:error_message pair.\n\n`Note: Your model must be registered with Admin.`\n\n``run_form_runners``\n++++++++++++++++++++\n\nYou can run a ``FormRunner`` for every CRF/Requisition model in a module:\n\n.. code-block:: python\n\n from django.apps import apps as django_apps\n from edc_form_runners.run_form_runners import run_form_runners\n\n run_form_runners(app_labels=[\"intecomm_subject\"])\n\n\nor just list a few models explicitly:\n\n.. code-block:: python\n\n from django.apps import apps as django_apps\n from edc_form_runners.run_form_runners import run_form_runners\n\n run_form_runners(model_names=[\"intecomm_subject.vitals\", \"intecomm_subject.medications\"])\n\n\nCustom FormRunners\n++++++++++++++++++\n\nYou may wish to ignore some errors; that is, prevent ``FormRunner`` from creating an ``Issue`` instance\nfor specific fields that do not validate. To do this create a custom ``FormRunner`` for your model\nand list the field names to exclude:\n\n.. code-block:: python\n\n class HtnMedicationAdherenceFormRunner(FormRunner):\n model_name = \"intecomm_subject.htnmedicationadherence\"\n exclude_formfields = [\"pill_count\"]\n\n\nNow you can use the custom ``FormRunner``:\n\n.. code-block:: python\n\n runner = HtnMedicationAdherenceFormRunner()\n runner.run_all()\n\nif field ``pill_count`` does not validate, the error message will not be written to the ``Issues`` table.\n\nRegistering Custom FormRunners\n++++++++++++++++++++++++++++++\n\nA custom ``FormRunner`` must be registered to be used by ``edc_form_runners``.\n\nDeclare your custom ``FormRunnners`` in module ``form_runners.py`` in the root of your app:\n\n.. code-block:: python\n\n # form_runners.py\n from edc_form_runners.decorators import register\n from edc_form_runners.form_runner import FormRunner\n\n\n @register\n class HtnMedicationAdherenceFormRunner(FormRunner):\n model_name = \"intecomm_subject.htnmedicationadherence\"\n exclude_formfields = [\"pill_count\"]\n\n @register\n class DmMedicationAdherenceFormRunner(FormRunner):\n model_name = \"intecomm_subject.dmmedicationadherence\"\n exclude_formfields = [\"pill_count\"]\n\n\nThe ``register`` decorator registers the custom classes with ``site_form_runners``.\n\n\n``get_form_runner``\n+++++++++++++++++++\n\n``edc_form_runners`` gets ``FormRunners`` using ``get_form_runner``.\nGiven a model name in ``label_lower`` format, ``get_form_runner`` checks the site global (``site_form_runners``) and returns\na custom ``FormRunner``, if it exists, otherwise returns the default ``FormRunner``.\n\nIn your code you should use ``get_form_runner``:\n\n.. code-block:: python\n\n # good, returned DmMedicationAdherenceFormRunner instead of the default FormRunner\n runner = get_form_runner(\"intecomm_subject.dmmedicationadherence\")\n runner.run()\n\n # works but does not use your custom form runner\n runner = FormRunner(\"intecomm_subject.dmmedicationadherence\")\n runner.run_all()\n\n\nManagement Command ``run_form_runners``\n+++++++++++++++++++++++++++++++++++++++\n\nYou can use the management command ``run_form_runners`` to run form runners for some or\nall CRF/Requisitions. Run this command to initially populate ``Issue`` table and whenever you\nchange validation logic for a form.\n\nPass the management command one or more app_labels separated by comma:\n\n.. code-block:: bash\n\n >>> python manage.py run_form_runners -a intecomm_subject\n\nor pass one or more model names (label_lower format) separated by comma:\n\n.. code-block:: bash\n\n >>> python manage.py run_form_runners -m intecomm_subject.vitals,intecomm_subject.dmmedicationadherence\n\nYou can skip a model as well:\n\n.. code-block:: bash\n\n >>> python manage.py run_form_runners -a intecomm_subject -s intecomm_subject.medicationadherence\n\n``Issue`` ChangeList\n++++++++++++++++++++\n\nThe ``ChangeList`` for the ``Issue model`` is available in ``edc_data_manager`` and ``edc_form_runners``.\nYou would typically use the one in ``edc_data_manager``.\n\nFrom the change list you can:\n\n* search, filter and re-order\n* refresh selected ``Issue`` instances from the action menu.\n* navigate to a subject`s dashboard\n\nIntegrated with the Subject Dashboard\n+++++++++++++++++++++++++++++++++++++\n\nThe subject dashboard shows an \"Issues\" badge next to a CRF or Requisition if one exists. You can\nhover over the badge to see some of the error messages detected when the ``FormRunner`` last ran.\n\nIf a user edits a CRF with a detected issue and the corrected form validates withour error, the\n``Issue`` instance is deleted and the badge is no longer displayed.\n(See also ``signals.py``)\n\n\n``FormRunner`` is ``clinicedc`` specific\n++++++++++++++++++++++++++++++++++++++++\nAt the moment, the ``FormRunner`` class is currently ``clinicedc`` specific in that it only works for models with a\n``subject_identifier`` or related_visit FK (e.g. ``subject_visit``).\n\nThe ``post_save`` signal that updates Issues listens for ``clinicedc`` CRFs and Requisitions by testing if the model instance\nis an instance of ``CrfModelMixin``, ``CrfNoManagerModelMixin`` or ``RequisitionModelMixin``.\n\n\n.. |pypi| image:: https://img.shields.io/pypi/v/edc-form-runners.svg\n :target: https://pypi.python.org/pypi/edc-form-runners\n\n.. |actions| image:: https://github.com/clinicedc/edc-form-runners/actions/workflows/build.yml/badge.svg\n :target: https://github.com/clinicedc/edc-form-runners/actions/workflows/build.yml\n\n.. |codecov| image:: https://codecov.io/gh/clinicedc/edc-form-runners/branch/develop/graph/badge.svg\n :target: https://codecov.io/gh/clinicedc/edc-form-runners\n\n.. |downloads| image:: https://pepy.tech/badge/edc-form-runners\n :target: https://pepy.tech/project/edc-form-runners\n\n",
"bugtrack_url": null,
"license": "GPL license, see LICENSE",
"summary": "Classes to manually run form validation for clinicedc/edc projects",
"version": "0.3.10",
"project_urls": {
"Homepage": "https://github.com/clinicedc/edc-form-runners"
},
"split_keywords": [
"django edc",
" modelform",
" validation",
" clinicedc",
" clinical trials"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "27a92623568a8475b674b059006c8db4e7f1b99af94ec187e790f9980f218438",
"md5": "d4f1651fff6a8d3f5d0b06617c8f6717",
"sha256": "54ca6fdbc4a8d6aaad713d8cd9155db44a34f4a741aebedfa98d4e936f67a397"
},
"downloads": -1,
"filename": "edc_form_runners-0.3.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4f1651fff6a8d3f5d0b06617c8f6717",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 47538,
"upload_time": "2024-03-26T05:00:17",
"upload_time_iso_8601": "2024-03-26T05:00:17.625598Z",
"url": "https://files.pythonhosted.org/packages/27/a9/2623568a8475b674b059006c8db4e7f1b99af94ec187e790f9980f218438/edc_form_runners-0.3.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6fa1725f02fcdf2f35667aae571c2efd735efc5d3d8815cc27ce53d7fbc8b2ad",
"md5": "e4d23fb5425ca4a63271b46bfc15dc3c",
"sha256": "835bed0fc7c11754705e2ba123ee483ec78ef33b816f26f53602d7a4335ca03b"
},
"downloads": -1,
"filename": "edc-form-runners-0.3.10.tar.gz",
"has_sig": false,
"md5_digest": "e4d23fb5425ca4a63271b46bfc15dc3c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 44753,
"upload_time": "2024-03-26T05:00:20",
"upload_time_iso_8601": "2024-03-26T05:00:20.891969Z",
"url": "https://files.pythonhosted.org/packages/6f/a1/725f02fcdf2f35667aae571c2efd735efc5d3d8815cc27ce53d7fbc8b2ad/edc-form-runners-0.3.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-26 05:00:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "clinicedc",
"github_project": "edc-form-runners",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "edc-form-runners"
}
JSON
