edc-form-runners


Nameedc-form-runners JSON
Version 0.3.11 PyPI version JSON
download
home_pagehttps://github.com/clinicedc/edc-form-runners
SummaryClasses to manually run form validation for clinicedc/edc projects
upload_time2024-11-13 18:04:52
maintainerNone
docs_urlNone
authorErik van Widenfelt
requires_python>=3.12
licenseGPL license, see LICENSE
keywords django edc modelform validation clinicedc clinical trials
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            |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.12",
    "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/06/12/e93baf3a08a15c7394669bf3a91cfb251d76f2d29788ecf97f8df2b7ed61/edc_form_runners-0.3.11.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.11",
    "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": "31b6feae90d4b43c5dd729a1f7e66c15a5fe751ed1c54b658035b9ec38a9e57d",
                "md5": "0e495c046e0db97b48e06c98749b6945",
                "sha256": "bc0cfff9f081f0e9e6da51b7967515b0e3f2ea7b4540e19f1edd70fe53ea7065"
            },
            "downloads": -1,
            "filename": "edc_form_runners-0.3.11-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0e495c046e0db97b48e06c98749b6945",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 48675,
            "upload_time": "2024-11-13T18:04:49",
            "upload_time_iso_8601": "2024-11-13T18:04:49.642085Z",
            "url": "https://files.pythonhosted.org/packages/31/b6/feae90d4b43c5dd729a1f7e66c15a5fe751ed1c54b658035b9ec38a9e57d/edc_form_runners-0.3.11-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0612e93baf3a08a15c7394669bf3a91cfb251d76f2d29788ecf97f8df2b7ed61",
                "md5": "291afde3a3cb58de37e960e511dda6c9",
                "sha256": "59f95242eaa7f415153d49ba00225721673959b6b64214fa7f1a46f1cad14484"
            },
            "downloads": -1,
            "filename": "edc_form_runners-0.3.11.tar.gz",
            "has_sig": false,
            "md5_digest": "291afde3a3cb58de37e960e511dda6c9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 44453,
            "upload_time": "2024-11-13T18:04:52",
            "upload_time_iso_8601": "2024-11-13T18:04:52.284756Z",
            "url": "https://files.pythonhosted.org/packages/06/12/e93baf3a08a15c7394669bf3a91cfb251d76f2d29788ecf97f8df2b7ed61/edc_form_runners-0.3.11.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-13 18:04:52",
    "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"
}
        
Elapsed time: 0.72203s