edc-device


Nameedc-device JSON
Version 0.3.17 PyPI version JSON
download
home_pagehttps://github.com/clinicedc/edc-device
SummaryGet info on a data collection device for clinicedc/edc projects
upload_time2024-01-29 05:28:21
maintainer
docs_urlNone
authorErik van Widenfelt
requires_python>=3.11
licenseGPL license, see LICENSE
keywords django edc clinicedc clinical trials
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            |pypi| |actions| |coverage|


edc-device
----------

``edc-device`` provides device roles unique device IDs for hosts and clients where the hostname may not be reliable. Hosts can be group as servers, clients, node_servers and some of their functionality limited according to this role.

A unique device ID is used to seed unique subject and sample identifiers. Uniqueness is evaluated during deployment.

Device information is set in and read from ``edc_device.apps.AppConfig``.

You should subclass into your projects ``apps.py`` like this, for example:

.. code-block:: python

    from edc_device.apps import AppConfig as EdcDeviceAppConfigParent

    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):
        device_id = '32'
        device_role = CLIENT
        device_permissions = DevicePermissions(
            plot_add, plot_change, ...)

and then in your settings:

.. code-block:: python

    INSTALLED_APPS = [
        ...
        my_app.apps.EdcDeviceAppConfig,
        myapp.apps.AppConfig',
    ]

Include in your ``urls.py``:

.. code-block:: python

    urlpatterns = [
        ...
        path('edc_device/', include('edc_device.urls')),
        ...
    ]

To get to the Edc Device home page, reverse the url like this:

.. code-block:: python

    reverse('edc_device:home_url')


Usage
=====


A ``client`` might look like this:

.. code-block:: python

    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):
        device_id = '18'
        node_server_id_list = [97, 98, 99]
        middleman_id_list = [95, 96]

    >>> from django.apps import apps as django_apps
    >>> app_config = django_apps.get_app_config('edc_device')
    >>> app_config.device_id
    '18'
    >>> app_config.is_client
    True
    >>> app_config.device_role
    'Client'

A node server server might look like this:

.. code-block:: python

    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):
        device_id = '98'
        node_server_id_list = [97, 98, 99]
        middleman_id_list = [95, 96]

    >>> from django.apps import apps as django_apps
    >>> app_config = django_apps.get_app_config('edc_device')
    >>> app_config.device_id
    '98'
    >>> app_config.is_node_server
    True
    >>> app_config.device_role
    'NodeServer'

A middleman server might look like this:

.. code-block:: python

    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):
        device_id = '95'
        node_server_id_list = [97, 98, 99]
        middleman_id_list = [95, 96]

    >>> from django.apps import apps as django_apps
    >>> app_config = django_apps.get_app_config('edc_device')
    >>> app_config.device_id
    '95'
    >>> app_config.is_middleman
    True
    >>> app_config.device_role
    'Middleman'

The central server might look like this:

.. code-block:: python

    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):
        device_id = '99'
        node_server_id_list = [97, 98, 99]
        middleman_id_list = [95, 96]

    >>> from django.apps import apps as django_apps
    >>> app_config = django_apps.get_app_config('edc_device')
    >>> app_config.device_id
    '99'
    >>> app_config.is_middleman
    True
    >>> app_config.device_role
    'CentralServer'


See also ``django-collect-offline``.


Device Permissions by Model
===========================

You can use the device role, or the device ID, to limit ADD/CHANGE permissions on a model.

``edc-device`` AppConfig maintains a collection of ``DeviceAddPermission`` and ``DeviceChangePermission`` instances that are inspected in the ``save`` method of a model using the ``DeviceModelMixin``.

To declare a ``DeviceAddPermission`` object:

.. code-block:: python

    test_model_add = DeviceAddPermission(
        model='my_app.mymodel, device_roles=[NODE_SERVER, CENTRAL_SERVER])

To declare a ``DeviceChangePermission`` object:

.. code-block:: python

    test_model_change = DeviceChangePermission(
        model='my_app.mymodel, device_roles=[CLIENT])

This means that if ``app_config.device_role`` is anything other than ``NODE_SERVER`` or ``CENTRAL_SERVER``, the save method will raise a ``DevicePermissionsAddError``.

To register the instances with ``edc_device.apps.AppConfig.device_permissions``:

.. code-block:: python

    device_permissions = DevicePermissions(test_model_add, test_model_change)

This means that if ``app_config.device_role`` is anything other than ``CLIENT``, the save method will raise a ``DevicePermissionsChangeError``.

On boot up you should see:

.. code-block:: python

    Loading Edc Device ...
      * device id is '10'.
      * device role is 'Client'.
      * device permissions exist for:
        - edc_device.testmodel ADD NodeServer,CentralServer
        - edc_device.testmodel CHANGE Client
    Done loading Edc Device.

Models declared with the ``EdcDeviceModelMixin`` check the device permissions collection on save. Note the model mixin is already declared with ``BaseUuidModel``.

.. code-block:: python

    from edc_model.models import BaseUuidModel

    class TestModel(BaseUuidModel):
        pass


Declaring device permissions directly on model ``Meta`` class:
==============================================================

You can declare device permissions on ``Meta.device_permissions`` in the same way as above.

.. code-block:: python

    [...]
    class Meta(DeviceModelMixin.Meta):
        device_permissions = DevicePermissions(...)

Both ``Meta`` and ``AppConfig`` device permissions will be called, where the ``Meta`` class object will be called first.

Disable device permissions by model instance:
=============================================

You can disable device permissions ``per model instance`` by setting ``check_device_permissions`` to ``False``


Customizing Device Permissions
==============================

The ADD and CHANGE device permission objects by default inspect the model's ``id``. If ``obj.id`` is ``None``, it as an ADD model operation; If ``obj.id`` is not ``None``, it is a CHANGE model operation.

You can change this by overriding the ``model_operation`` method. The ``model_operation`` must return ``None`` or some value, such as ``self.label``.

For example:

.. code-block:: python

    # default for DeviceAddPermission
    label = 'ADD'

    def model_operation(self, model_obj=None, **kwargs):
        if not model_obj.id:
            return self.label
        return None

    # overridden
    def model_operation(self, model_obj=None, **kwargs):
        """Return ADD if both id and plot identifier are None.
        """
        if not model_obj.id and not obj.plot_identifier:
            return self.label
        return None



.. |pypi| image:: https://img.shields.io/pypi/v/edc-device.svg
    :target: https://pypi.python.org/pypi/edc-device

.. |actions| image:: https://github.com/clinicedc/edc-device/actions/workflows/build.yml/badge.svg
  :target: https://github.com/clinicedc/edc-device/actions/workflows/build.yml

.. |coverage| image:: https://coveralls.io/repos/github/clinicedc/edc-device/badge.svg?branch=develop
    :target: https://coveralls.io/github/clinicedc/edc-device?branch=develop


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/clinicedc/edc-device",
    "name": "edc-device",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": "",
    "keywords": "django Edc clinicedc,clinical trials",
    "author": "Erik van Widenfelt",
    "author_email": "ew2789@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/8c/1f/5dde00dc285381ff22fef9edac655ddf1706b69ab1643b69ae8ae71a320b/edc-device-0.3.17.tar.gz",
    "platform": null,
    "description": "|pypi| |actions| |coverage|\n\n\nedc-device\n----------\n\n``edc-device`` provides device roles unique device IDs for hosts and clients where the hostname may not be reliable. Hosts can be group as servers, clients, node_servers and some of their functionality limited according to this role.\n\nA unique device ID is used to seed unique subject and sample identifiers. Uniqueness is evaluated during deployment.\n\nDevice information is set in and read from ``edc_device.apps.AppConfig``.\n\nYou should subclass into your projects ``apps.py`` like this, for example:\n\n.. code-block:: python\n\n    from edc_device.apps import AppConfig as EdcDeviceAppConfigParent\n\n    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):\n        device_id = '32'\n        device_role = CLIENT\n        device_permissions = DevicePermissions(\n            plot_add, plot_change, ...)\n\nand then in your settings:\n\n.. code-block:: python\n\n    INSTALLED_APPS = [\n        ...\n        my_app.apps.EdcDeviceAppConfig,\n        myapp.apps.AppConfig',\n    ]\n\nInclude in your ``urls.py``:\n\n.. code-block:: python\n\n    urlpatterns = [\n        ...\n        path('edc_device/', include('edc_device.urls')),\n        ...\n    ]\n\nTo get to the Edc Device home page, reverse the url like this:\n\n.. code-block:: python\n\n    reverse('edc_device:home_url')\n\n\nUsage\n=====\n\n\nA ``client`` might look like this:\n\n.. code-block:: python\n\n    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):\n        device_id = '18'\n        node_server_id_list = [97, 98, 99]\n        middleman_id_list = [95, 96]\n\n    >>> from django.apps import apps as django_apps\n    >>> app_config = django_apps.get_app_config('edc_device')\n    >>> app_config.device_id\n    '18'\n    >>> app_config.is_client\n    True\n    >>> app_config.device_role\n    'Client'\n\nA node server server might look like this:\n\n.. code-block:: python\n\n    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):\n        device_id = '98'\n        node_server_id_list = [97, 98, 99]\n        middleman_id_list = [95, 96]\n\n    >>> from django.apps import apps as django_apps\n    >>> app_config = django_apps.get_app_config('edc_device')\n    >>> app_config.device_id\n    '98'\n    >>> app_config.is_node_server\n    True\n    >>> app_config.device_role\n    'NodeServer'\n\nA middleman server might look like this:\n\n.. code-block:: python\n\n    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):\n        device_id = '95'\n        node_server_id_list = [97, 98, 99]\n        middleman_id_list = [95, 96]\n\n    >>> from django.apps import apps as django_apps\n    >>> app_config = django_apps.get_app_config('edc_device')\n    >>> app_config.device_id\n    '95'\n    >>> app_config.is_middleman\n    True\n    >>> app_config.device_role\n    'Middleman'\n\nThe central server might look like this:\n\n.. code-block:: python\n\n    class EdcDeviceAppConfig(EdcDeviceAppConfigParent):\n        device_id = '99'\n        node_server_id_list = [97, 98, 99]\n        middleman_id_list = [95, 96]\n\n    >>> from django.apps import apps as django_apps\n    >>> app_config = django_apps.get_app_config('edc_device')\n    >>> app_config.device_id\n    '99'\n    >>> app_config.is_middleman\n    True\n    >>> app_config.device_role\n    'CentralServer'\n\n\nSee also ``django-collect-offline``.\n\n\nDevice Permissions by Model\n===========================\n\nYou can use the device role, or the device ID, to limit ADD/CHANGE permissions on a model.\n\n``edc-device`` AppConfig maintains a collection of ``DeviceAddPermission`` and ``DeviceChangePermission`` instances that are inspected in the ``save`` method of a model using the ``DeviceModelMixin``.\n\nTo declare a ``DeviceAddPermission`` object:\n\n.. code-block:: python\n\n    test_model_add = DeviceAddPermission(\n        model='my_app.mymodel, device_roles=[NODE_SERVER, CENTRAL_SERVER])\n\nTo declare a ``DeviceChangePermission`` object:\n\n.. code-block:: python\n\n    test_model_change = DeviceChangePermission(\n        model='my_app.mymodel, device_roles=[CLIENT])\n\nThis means that if ``app_config.device_role`` is anything other than ``NODE_SERVER`` or ``CENTRAL_SERVER``, the save method will raise a ``DevicePermissionsAddError``.\n\nTo register the instances with ``edc_device.apps.AppConfig.device_permissions``:\n\n.. code-block:: python\n\n    device_permissions = DevicePermissions(test_model_add, test_model_change)\n\nThis means that if ``app_config.device_role`` is anything other than ``CLIENT``, the save method will raise a ``DevicePermissionsChangeError``.\n\nOn boot up you should see:\n\n.. code-block:: python\n\n    Loading Edc Device ...\n      * device id is '10'.\n      * device role is 'Client'.\n      * device permissions exist for:\n        - edc_device.testmodel ADD NodeServer,CentralServer\n        - edc_device.testmodel CHANGE Client\n    Done loading Edc Device.\n\nModels declared with the ``EdcDeviceModelMixin`` check the device permissions collection on save. Note the model mixin is already declared with ``BaseUuidModel``.\n\n.. code-block:: python\n\n    from edc_model.models import BaseUuidModel\n\n    class TestModel(BaseUuidModel):\n        pass\n\n\nDeclaring device permissions directly on model ``Meta`` class:\n==============================================================\n\nYou can declare device permissions on ``Meta.device_permissions`` in the same way as above.\n\n.. code-block:: python\n\n    [...]\n    class Meta(DeviceModelMixin.Meta):\n        device_permissions = DevicePermissions(...)\n\nBoth ``Meta`` and ``AppConfig`` device permissions will be called, where the ``Meta`` class object will be called first.\n\nDisable device permissions by model instance:\n=============================================\n\nYou can disable device permissions ``per model instance`` by setting ``check_device_permissions`` to ``False``\n\n\nCustomizing Device Permissions\n==============================\n\nThe ADD and CHANGE device permission objects by default inspect the model's ``id``. If ``obj.id`` is ``None``, it as an ADD model operation; If ``obj.id`` is not ``None``, it is a CHANGE model operation.\n\nYou can change this by overriding the ``model_operation`` method. The ``model_operation`` must return ``None`` or some value, such as ``self.label``.\n\nFor example:\n\n.. code-block:: python\n\n    # default for DeviceAddPermission\n    label = 'ADD'\n\n    def model_operation(self, model_obj=None, **kwargs):\n        if not model_obj.id:\n            return self.label\n        return None\n\n    # overridden\n    def model_operation(self, model_obj=None, **kwargs):\n        \"\"\"Return ADD if both id and plot identifier are None.\n        \"\"\"\n        if not model_obj.id and not obj.plot_identifier:\n            return self.label\n        return None\n\n\n\n.. |pypi| image:: https://img.shields.io/pypi/v/edc-device.svg\n    :target: https://pypi.python.org/pypi/edc-device\n\n.. |actions| image:: https://github.com/clinicedc/edc-device/actions/workflows/build.yml/badge.svg\n  :target: https://github.com/clinicedc/edc-device/actions/workflows/build.yml\n\n.. |coverage| image:: https://coveralls.io/repos/github/clinicedc/edc-device/badge.svg?branch=develop\n    :target: https://coveralls.io/github/clinicedc/edc-device?branch=develop\n\n",
    "bugtrack_url": null,
    "license": "GPL license, see LICENSE",
    "summary": "Get info on a data collection device for clinicedc/edc projects",
    "version": "0.3.17",
    "project_urls": {
        "Homepage": "https://github.com/clinicedc/edc-device"
    },
    "split_keywords": [
        "django edc clinicedc",
        "clinical trials"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "66a600d7258b6d864269062c8a548736b116fb859bb6515fc04554e03d9057de",
                "md5": "ee5b165ee1c3d7c7cd653eb576f61d23",
                "sha256": "d6999f68f5660410c39d15e4c4624072700827087f68ff075b056b9b3b7a1b0e"
            },
            "downloads": -1,
            "filename": "edc_device-0.3.17-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ee5b165ee1c3d7c7cd653eb576f61d23",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 28316,
            "upload_time": "2024-01-29T05:28:20",
            "upload_time_iso_8601": "2024-01-29T05:28:20.456369Z",
            "url": "https://files.pythonhosted.org/packages/66/a6/00d7258b6d864269062c8a548736b116fb859bb6515fc04554e03d9057de/edc_device-0.3.17-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "8c1f5dde00dc285381ff22fef9edac655ddf1706b69ab1643b69ae8ae71a320b",
                "md5": "c3e9c211d62aaaea863f7c1c4344f0ce",
                "sha256": "509260e540b36d82925155cc60e68cb038cd05dcc005a2a72a467491179dc2d7"
            },
            "downloads": -1,
            "filename": "edc-device-0.3.17.tar.gz",
            "has_sig": false,
            "md5_digest": "c3e9c211d62aaaea863f7c1c4344f0ce",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 29430,
            "upload_time": "2024-01-29T05:28:21",
            "upload_time_iso_8601": "2024-01-29T05:28:21.962676Z",
            "url": "https://files.pythonhosted.org/packages/8c/1f/5dde00dc285381ff22fef9edac655ddf1706b69ab1643b69ae8ae71a320b/edc-device-0.3.17.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-29 05:28:21",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "clinicedc",
    "github_project": "edc-device",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "lcname": "edc-device"
}
        
Elapsed time: 1.30113s