|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": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "django Edc clinicedc, clinical trials",
"author": "Erik van Widenfelt",
"author_email": "ew2789@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/18/4c/d2282cdee15db314a7bdadcac514f89d7d8bbae8b131f89b5496a04c3d4e/edc_device-0.3.18.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",
"bugtrack_url": null,
"license": "GPL license, see LICENSE",
"summary": "Get info on a data collection device for clinicedc/edc projects",
"version": "0.3.18",
"project_urls": {
"Homepage": "https://github.com/clinicedc/edc-device"
},
"split_keywords": [
"django edc clinicedc",
" clinical trials"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aaed375cbd708af31ab03d18139ebca63e3da44855fa19cf69234382bca86d82",
"md5": "bfb7e59be09322b04dbc47987817a0d2",
"sha256": "c1f18e2601647fa8a622b13e610c7b2df81406224695c85ebcbd29d7d2cab543"
},
"downloads": -1,
"filename": "edc_device-0.3.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfb7e59be09322b04dbc47987817a0d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 28317,
"upload_time": "2024-11-20T22:52:39",
"upload_time_iso_8601": "2024-11-20T22:52:39.547232Z",
"url": "https://files.pythonhosted.org/packages/aa/ed/375cbd708af31ab03d18139ebca63e3da44855fa19cf69234382bca86d82/edc_device-0.3.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "184cd2282cdee15db314a7bdadcac514f89d7d8bbae8b131f89b5496a04c3d4e",
"md5": "3a02fe2de7b9d3cdf76b7056e598bba4",
"sha256": "20777f14cbd4294b456d7c2ad481e629b76fd4cec864e5eb7886066ab40926ac"
},
"downloads": -1,
"filename": "edc_device-0.3.18.tar.gz",
"has_sig": false,
"md5_digest": "3a02fe2de7b9d3cdf76b7056e598bba4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 29514,
"upload_time": "2024-11-20T22:52:40",
"upload_time_iso_8601": "2024-11-20T22:52:40.584074Z",
"url": "https://files.pythonhosted.org/packages/18/4c/d2282cdee15db314a7bdadcac514f89d7d8bbae8b131f89b5496a04c3d4e/edc_device-0.3.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 22:52:40",
"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"
}
JSON
