# DRF Integrations Framework
[](https://github.com/pre-commit/pre-commit)
[](https://actions-badge.atrox.dev/yoyowallet/drf-integrations-framework/goto?ref=master)
DRF Integrations Framework is a toolkit that plugs in to [Django REST Framework](https://www.django-rest-framework.org/)
and simplifies the management of third party integrations. If you find yourself connecting to multiple services with
different sets of credentials, or handling multiple inbound requests from third party services, DRF Integrations
Framework will probably simplify that for you. DRF Integrations Framework will help you split the responsibilities
between the source/destiny of events, how these requests are authenticated and the business logic associated to them.
## Requirements
- Python 3.7+
- Django 2.2+
- Django REST Framework 3.9.2+
- Django OAuth Toolkit 1.7.1+
## Installation
The following library is required in order to build on `Linux systems`. It fixes the
problem where `Error: pg_config executable not found.` is given when installing psycopg2
via `poetry install`
```
sudo apt install libpq-dev
```
Install from PyPi:
```bash
pip install drf-integrations-framework
```
Or install from source:
```bash
pip install https://github.com/yoyowallet/drf-integrations-framework/archive/v0.7.1.tar.gz
```
Add the apps to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
...,
"rest_framework",
"oauth2_provider",
"drf_integrations",
]
```
If you are going to configure any inbound integration, you will want to add the integration URLs to your `urls.py`:
```python
from drf_integrations import integrations
urlpatterns = [
...
] + integrations.get_urls()
```
## Configuration
### Settings
DRF Integrations Framework relies on Django OAuth Toolkit to manage third party applications. In order to be able to use
it, first you'll need to configure DOT by setting (at least) the model references in your settings.
```python
OAUTH2_PROVIDER_APPLICATION_MODEL = "drf_integrations.Application"
OAUTH2_PROVIDER_ACCESS_TOKEN_MODEL = "drf_integrations.AccessToken"
OAUTH2_PROVIDER_GRANT_MODEL = "drf_integrations.Grant"
OAUTH2_PROVIDER_REFRESH_TOKEN_MODEL = "drf_integrations.RefreshToken"
```
Then, similarly, you will have to configure the model for the integrations.
```python
INTEGRATIONS_APPLICATION_INSTALLATION_MODEL = "drf_integrations.ApplicationInstallation"
```
You will also have to configure how the integrations are stored in the database. On the one hand, you will have to set
the type of JSON field your DB uses. On the other hand, you will have to set the name of the attribute where you want to
relate the integrations.
```python
DB_BACKEND_JSON_FIELD = "django.db.models.JSONField"
INTEGRATIONS_APPLICATION_INSTALLATION_INSTALL_ATTRIBUTE = "organisation"
```
Finally, you have to set the list of integrations that are available in your system (see the following section to learn
about creating integrations).
```python
INSTALLED_INTEGRATIONS = [
"example.drf_integrations_example.api.integrations.APIClientIntegration",
]
```
### Creating integrations
An integration is represented by an extension of `BaseIntegration`. Then, the integration will be available to be
installed to different clients (as related with the previously configured
`INTEGRATIONS_APPLICATION_INSTALLATION_INSTALL_ATTRIBUTE`) once it is stored into an `Application`. This can be done in
two different ways:
1. Internal integrations (or non-local integrations) are those that can be configured once and installed to different clients with different
parameters. For example, your system may connect to Mixpanel, the connections and interactions with the service are all
the same, only the secret in the connection changes.
These will only have 1 `Application` object in the database, and it can be related to multiple installations. They
can also be automatically created by using the `syncregistry` management command.
```bash
python manage.py syncregistry
```
1. Local integrations are those that are specific to just one client. For example, OAuth clients are local, there is
1 application per client, which will have the specific credentials for them, so they can only be installed once. These
are usually created on demand as required by clients.
An integration broadly has 3 functions:
1. Generates a list of URLs that a third party represented by this integration can connect to.
Mainly used for inward integrations.
1. Returns a client that can connect to the third party it represents. Mainly used for outward integrations.
1. Produce queryset filter lookups to search for installations of the integration.
Once you have a class inheriting from `BaseIntegration` that represents a third party, simply add it to
`INSTALLED_INTEGRATIONS` in your settings and the sky is the limit! You can create custom authentication backends,
permissions, event hooks... Take a look at [the example](example) to see some basic examples of how you can make use
of DRF Integrations Framework.
### Preconfigured
There are some features that DRF Integrations Framework provides out of the box.
- Admin model for `ApplicationInstallation` that already handles integration-specific configuration via dynamic forms.
- Automatic form validation for integrations that have one.
- An authentication backend for local OAuth2 integrations
(`drf_integrations.auth_backends.IntegrationOAuth2Authentication`).
## Running the tests
To run the tests you need to have a postgresql server running on localhost and have a
postgres user/role defined. To create the postgres user and role you can use the
following:
```psql -c 'CREATE ROLE postgres WITH LOGIN SUPERUSER' ```
To run the tests execute the following
```make tests```
If running tests under pycharm ensure that `python tests` -> `pytest` is used and set
the `Additional Arguments` to `--no-migrations`
Failing to specify `--no-migrations` will result in the following error:
```
ValueError: Related model 'oauth2_provider.idtoken' cannot be resolved
```
## Changelog
See [Releases](https://github.com/yoyowallet/drf-integrations-framework/releases)
## Authors
DRF Integrations Framework is an original idea by [@jianyuan](https://github.com/jianyuan), developed and maintained by
the platform team at [@yoyowallet](https://github.com/yoyowallet).
Raw data
{
"_id": null,
"home_page": "https://github.com/yoyowallet/drf-integrations-framework",
"name": "drf-integrations-framework",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<3.12",
"maintainer_email": "",
"keywords": "drf",
"author": "Yoyo",
"author_email": "dev@yoyowallet.com",
"download_url": "https://files.pythonhosted.org/packages/6a/21/7b8e038a3dad4a2952e13545122a3171574880906fcd3057468600766aa6/drf_integrations_framework-0.8.6.tar.gz",
"platform": null,
"description": "# DRF Integrations Framework\n\n[](https://github.com/pre-commit/pre-commit)\n[](https://actions-badge.atrox.dev/yoyowallet/drf-integrations-framework/goto?ref=master)\n\nDRF Integrations Framework is a toolkit that plugs in to [Django REST Framework](https://www.django-rest-framework.org/)\nand simplifies the management of third party integrations. If you find yourself connecting to multiple services with\ndifferent sets of credentials, or handling multiple inbound requests from third party services, DRF Integrations\nFramework will probably simplify that for you. DRF Integrations Framework will help you split the responsibilities\nbetween the source/destiny of events, how these requests are authenticated and the business logic associated to them.\n\n## Requirements\n- Python 3.7+\n- Django 2.2+\n- Django REST Framework 3.9.2+\n- Django OAuth Toolkit 1.7.1+\n\n## Installation\n\nThe following library is required in order to build on `Linux systems`. It fixes the\nproblem where `Error: pg_config executable not found.` is given when installing psycopg2\nvia `poetry install`\n```\nsudo apt install libpq-dev\n```\n\nInstall from PyPi:\n```bash\npip install drf-integrations-framework\n```\nOr install from source:\n```bash\npip install https://github.com/yoyowallet/drf-integrations-framework/archive/v0.7.1.tar.gz\n```\n\nAdd the apps to your `INSTALLED_APPS`:\n```python\nINSTALLED_APPS = [\n ...,\n \"rest_framework\",\n \"oauth2_provider\",\n \"drf_integrations\",\n]\n```\n\nIf you are going to configure any inbound integration, you will want to add the integration URLs to your `urls.py`:\n```python\nfrom drf_integrations import integrations\n\nurlpatterns = [\n ...\n] + integrations.get_urls()\n```\n\n## Configuration\n### Settings\nDRF Integrations Framework relies on Django OAuth Toolkit to manage third party applications. In order to be able to use\nit, first you'll need to configure DOT by setting (at least) the model references in your settings.\n```python\nOAUTH2_PROVIDER_APPLICATION_MODEL = \"drf_integrations.Application\"\nOAUTH2_PROVIDER_ACCESS_TOKEN_MODEL = \"drf_integrations.AccessToken\"\nOAUTH2_PROVIDER_GRANT_MODEL = \"drf_integrations.Grant\"\nOAUTH2_PROVIDER_REFRESH_TOKEN_MODEL = \"drf_integrations.RefreshToken\"\n```\nThen, similarly, you will have to configure the model for the integrations.\n```python\nINTEGRATIONS_APPLICATION_INSTALLATION_MODEL = \"drf_integrations.ApplicationInstallation\"\n```\nYou will also have to configure how the integrations are stored in the database. On the one hand, you will have to set\nthe type of JSON field your DB uses. On the other hand, you will have to set the name of the attribute where you want to\nrelate the integrations.\n```python\nDB_BACKEND_JSON_FIELD = \"django.db.models.JSONField\"\nINTEGRATIONS_APPLICATION_INSTALLATION_INSTALL_ATTRIBUTE = \"organisation\"\n```\nFinally, you have to set the list of integrations that are available in your system (see the following section to learn\nabout creating integrations).\n```python\nINSTALLED_INTEGRATIONS = [\n \"example.drf_integrations_example.api.integrations.APIClientIntegration\",\n]\n```\n### Creating integrations\nAn integration is represented by an extension of `BaseIntegration`. Then, the integration will be available to be\ninstalled to different clients (as related with the previously configured\n`INTEGRATIONS_APPLICATION_INSTALLATION_INSTALL_ATTRIBUTE`) once it is stored into an `Application`. This can be done in\ntwo different ways:\n1. Internal integrations (or non-local integrations) are those that can be configured once and installed to different clients with different\nparameters. For example, your system may connect to Mixpanel, the connections and interactions with the service are all\nthe same, only the secret in the connection changes.\n\n These will only have 1 `Application` object in the database, and it can be related to multiple installations. They\n can also be automatically created by using the `syncregistry` management command.\n ```bash\n python manage.py syncregistry\n ```\n\n1. Local integrations are those that are specific to just one client. For example, OAuth clients are local, there is\n1 application per client, which will have the specific credentials for them, so they can only be installed once. These\nare usually created on demand as required by clients.\n\nAn integration broadly has 3 functions:\n1. Generates a list of URLs that a third party represented by this integration can connect to.\nMainly used for inward integrations.\n1. Returns a client that can connect to the third party it represents. Mainly used for outward integrations.\n1. Produce queryset filter lookups to search for installations of the integration.\n\nOnce you have a class inheriting from `BaseIntegration` that represents a third party, simply add it to\n`INSTALLED_INTEGRATIONS` in your settings and the sky is the limit! You can create custom authentication backends,\npermissions, event hooks... Take a look at [the example](example) to see some basic examples of how you can make use\nof DRF Integrations Framework.\n\n### Preconfigured\nThere are some features that DRF Integrations Framework provides out of the box.\n\n- Admin model for `ApplicationInstallation` that already handles integration-specific configuration via dynamic forms.\n- Automatic form validation for integrations that have one.\n- An authentication backend for local OAuth2 integrations\n(`drf_integrations.auth_backends.IntegrationOAuth2Authentication`).\n\n## Running the tests\n\nTo run the tests you need to have a postgresql server running on localhost and have a\npostgres user/role defined. To create the postgres user and role you can use the\nfollowing:\n\n```psql -c 'CREATE ROLE postgres WITH LOGIN SUPERUSER' ```\n\nTo run the tests execute the following\n\n```make tests```\n\nIf running tests under pycharm ensure that `python tests` -> `pytest` is used and set\nthe `Additional Arguments` to `--no-migrations`\n\nFailing to specify `--no-migrations` will result in the following error:\n```\nValueError: Related model 'oauth2_provider.idtoken' cannot be resolved\n```\n\n## Changelog\nSee [Releases](https://github.com/yoyowallet/drf-integrations-framework/releases)\n\n## Authors\nDRF Integrations Framework is an original idea by [@jianyuan](https://github.com/jianyuan), developed and maintained by\nthe platform team at [@yoyowallet](https://github.com/yoyowallet).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django REST Framework plugin that simplifies the management of third party integrations",
"version": "0.8.6",
"project_urls": {
"Homepage": "https://github.com/yoyowallet/drf-integrations-framework",
"Repository": "https://github.com/yoyowallet/drf-integrations-framework"
},
"split_keywords": [
"drf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fca6e25f0ec90e24077c029985311fed5c10d23c1b00de9fba44f0613ac6851a",
"md5": "5334e9383eeecd54851419cde6fa35c8",
"sha256": "f8e63f6d2833ba4f79b7de224287dd062f011f02feef344aad9b3e3807e2c3aa"
},
"downloads": -1,
"filename": "drf_integrations_framework-0.8.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5334e9383eeecd54851419cde6fa35c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<3.12",
"size": 29445,
"upload_time": "2023-05-02T16:53:41",
"upload_time_iso_8601": "2023-05-02T16:53:41.918254Z",
"url": "https://files.pythonhosted.org/packages/fc/a6/e25f0ec90e24077c029985311fed5c10d23c1b00de9fba44f0613ac6851a/drf_integrations_framework-0.8.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a217b8e038a3dad4a2952e13545122a3171574880906fcd3057468600766aa6",
"md5": "78a68bc748f5f7ee3460ab85be8d7e6a",
"sha256": "ccd1e94d6a77979648e7c8350080e948a440e540e60b5efa0af3b216f6463768"
},
"downloads": -1,
"filename": "drf_integrations_framework-0.8.6.tar.gz",
"has_sig": false,
"md5_digest": "78a68bc748f5f7ee3460ab85be8d7e6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<3.12",
"size": 22661,
"upload_time": "2023-05-02T16:53:43",
"upload_time_iso_8601": "2023-05-02T16:53:43.039529Z",
"url": "https://files.pythonhosted.org/packages/6a/21/7b8e038a3dad4a2952e13545122a3171574880906fcd3057468600766aa6/drf_integrations_framework-0.8.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-02 16:53:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yoyowallet",
"github_project": "drf-integrations-framework",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "drf-integrations-framework"
}
JSON
