# DIMO Python Developer SDK
## Installation
You can install the SDK using `pip`
```bash
pip install dimo-python-sdk
```
## Unit Testing
Coming Soon
## API Documentation
Please visit the DIMO [Developer Documentation](https://docs.dimo.org/developer-platform) to learn more about building on DIMO and detailed information on the API.
### Developer License
In order to build on DIMO, you’ll need to get a [DIMO Developer License](https://docs.dimo.zone/developer-platform/getting-started/developer-license) via the [DIMO Dev Console](https://console.dimo.org/). The DIMO Developer license is our approach and design to a more secured, decentralized access control. As a developer, you will need to perform the following steps:
1. Sign Up for an Account - You can use your Google or Github account to register.
2. Complete Registration - Enter the details of the application that you’re building.
3. Create An App - Click “Create App”, fill out the form & select your preferred environment (at this time, please select “Production” until we’re ready to launch our Sandbox environment), then hit “Create Application”.
4. Finish Configuring Your Application - Once your project is initialized, you’ll use your connected wallet to generate an API Key and any optional Redirect URIs.
More information about this process can be found on our docs [here](https://docs.dimo.org/developer-platform/getting-started/developer-guide/developer-console)
## How to Use the SDK
Importing the SDK:
```python
from dimo import DIMO
```
Initiate the SDK depending on the envionrment of your interest, we currently support both `Production` and `Dev` environments:
```python
dimo = DIMO("Production")
```
or
```python
dimo = DIMO("Dev")
```
### Authentication
To get authenticated as a developer, you must have already obtained a [Developer License via the Console](https://docs.dimo.org/developer-platform/getting-started/developer-guide/developer-console#getting-a-license). To learn more about authentication, including the User JWT, Developer JWT, and Vehicle JWT needed for accessing certain endpoints, please read: [Authentication Docs](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication).
#### API Authentication
##### (Option 1) 3-Step Function Calls
The SDK offers 3 basic functions that maps to the steps listed in [Authentication](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication): `generate_challenge`, `sign_challenge`, and `submit_challenge`. You can use them accordingly depending on how you build your application.
```python
challenge = dimo.auth.generate_challenge(
client_id = '<client_id>',
domain = '<domain>',
address = '<address>'
)
signature = dimo.auth.sign_challenge(
message = challenge['challenge'],
private_key = '<private_key>'
)
tokens = dimo.auth.submit_challenge(
client_id = '<client_id>',
domain = '<domain>',
state = challenge['state'],
signature = signature
)
```
##### (Option 2) Auth Endpoint Shortcut Function
As mentioned earlier, this is the streamlined function call to directly get the `developer_jwt`. The `address` field in challenge generation is omitted since it is essentially the `client_id` of your application per Developer License:
```python
auth_header = dimo.auth.get_token(
client_id = '<client_id>',
domain = '<domain>',
private_key = '<private_key>'
)
# Store the Developer JWT from the auth_header dictionary
dev_jwt = auth_header["access_token"]
```
### Querying the DIMO REST API
The SDK uses the [requests](https://requests.readthedocs.io/en/latest/) library for making HTTP requests. You can perform a query like so:
```python
def decode_vin():
device_makes = dimo.device_definitions.decode_vin(
developer_jwt = dev_jwt,
country_code = "USA",
vin = "<VIN>"
)
# Do something with the response
```
#### Query Parameters
For query parameters, simply feed in an input that matches with the expected query parameters:
```python
dimo.device_definitions.search_device_definitions(
query = "Lexus gx 2023"
)
```
#### Vehicle JWTs
As the 2nd leg of the API authentication, applications may exchange for short-lived Vehicle JWTs for specific vehicles that granted privileges to the app. This uses the [DIMO Token Exchange API](https://docs.dimo.org/developer-platform/api-references/token-exchange-api).
For the end users of your application, they will need to share their vehicle permissions via the DIMO Mobile App or through your implementation of the [Login with DIMO flow](https://docs.dimo.org/developer-platform/getting-started/developer-guide/login-with-dimo). You can use the pre-built React component SDK, or redirect users to the URLs included in the documentation [here](https://docs.dimo.org/developer-platform/getting-started/developer-guide/login-with-dimo#dont-use-react).
Typically, any endpoints that uses a NFT `tokenId` in path parameters will require JWTs. You can use this flow to obtain a privilege token.
```python
get_vehicle_jwt = dimo.token_exchange.exchange(
developer_jwt = dev_jwt,
# The Developer JWT you received using either the three step function calls, or the .get_token() shortcut
privileges=[1, 3, 4, 5],
# The privileges you've set for this vehicle, in list format (e.g. [1, 3, 4, 5])
token_id="<token_id>"
# The Vehicle NFT Token ID that you are requesting permission to
)
vehicle_jwt = get_vehicle_jwt['token']
```
Once you have the privilege token, you can pipe it through to corresponding endpoints like so:
```python
def my_trips():
trip_data = dimo.trips.trips(
vehicle_jwt=vehicle_jwt,
token_id=<token_id>
)
return trip_data
```
### Querying the DIMO GraphQL API
The SDK accepts any type of valid custom GraphQL queries, but we've also included a few sample queries to help you understand the DIMO GraphQL APIs.
#### Authentication for GraphQL API
The GraphQL entry points are designed almost identical to the REST API entry points. For any GraphQL API that requires auth headers (Telemetry API for example), you can use the same pattern as you would in the REST protected endpoints.
```python
telemetry_data = dimo.telemetry.query(
vehicle_jwt=vehicle_jwt,
query= """
query {
some_valid_GraphQL_query
}
"""
)
```
#### Send a custom GraphQL query
To send a custom GraphQL query, you can simply call the `query` function on any GraphQL API Endpoints and pass in any valid GraphQL query. To check whether your GraphQL query is valid, please visit our [Identity API GraphQL Playground](https://identity-api.dimo.zone/) or [Telemetry API GraphQL Playground](https://telemetry-api.dimo.zone/).
```python
my_query = """
{
vehicles (first:10) {
totalCount
}
}
"""
total_network_vehicles = dimo.identity.query(query=my_query)
```
## How to Contribute to the SDK
You can read more about contributing [here](https://github.com/DIMO-Network/dimo-python-sdk/blob/dev-barrettk/CONTRIBUTING.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "dimo-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dimo, sdk, python, depin, web3",
"author": null,
"author_email": "Barrett Kowalsky <barrettkowalsky@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/18/caaf3e53e88288c2364def1b4b5b66e1a245e1ec021add00e9a5dcd02bc1/dimo_python_sdk-1.1.1.tar.gz",
"platform": null,
"description": "# DIMO Python Developer SDK\n\n## Installation\n\nYou can install the SDK using `pip`\n\n```bash\npip install dimo-python-sdk\n```\n\n## Unit Testing\n\nComing Soon\n\n## API Documentation\n\nPlease visit the DIMO [Developer Documentation](https://docs.dimo.org/developer-platform) to learn more about building on DIMO and detailed information on the API.\n\n\n### Developer License\n\nIn order to build on DIMO, you\u2019ll need to get a [DIMO Developer License](https://docs.dimo.zone/developer-platform/getting-started/developer-license) via the [DIMO Dev Console](https://console.dimo.org/). The DIMO Developer license is our approach and design to a more secured, decentralized access control. As a developer, you will need to perform the following steps:\n\n1. Sign Up for an Account - You can use your Google or Github account to register.\n2. Complete Registration - Enter the details of the application that you\u2019re building.\n3. Create An App - Click \u201cCreate App\u201d, fill out the form & select your preferred environment (at this time, please select \u201cProduction\u201d until we\u2019re ready to launch our Sandbox environment), then hit \u201cCreate Application\u201d.\n4. Finish Configuring Your Application - Once your project is initialized, you\u2019ll use your connected wallet to generate an API Key and any optional Redirect URIs.\n\nMore information about this process can be found on our docs [here](https://docs.dimo.org/developer-platform/getting-started/developer-guide/developer-console)\n\n## How to Use the SDK\n\nImporting the SDK:\n\n```python\nfrom dimo import DIMO\n```\n\nInitiate the SDK depending on the envionrment of your interest, we currently support both `Production` and `Dev` environments:\n\n```python\ndimo = DIMO(\"Production\")\n```\n\nor\n\n```python\ndimo = DIMO(\"Dev\")\n```\n\n### Authentication\n\nTo get authenticated as a developer, you must have already obtained a [Developer License via the Console](https://docs.dimo.org/developer-platform/getting-started/developer-guide/developer-console#getting-a-license). To learn more about authentication, including the User JWT, Developer JWT, and Vehicle JWT needed for accessing certain endpoints, please read: [Authentication Docs](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication). \n\n#### API Authentication\n\n##### (Option 1) 3-Step Function Calls\n\nThe SDK offers 3 basic functions that maps to the steps listed in [Authentication](https://docs.dimo.org/developer-platform/getting-started/developer-guide/authentication): `generate_challenge`, `sign_challenge`, and `submit_challenge`. You can use them accordingly depending on how you build your application.\n\n```python\n challenge = dimo.auth.generate_challenge(\n client_id = '<client_id>',\n domain = '<domain>',\n address = '<address>'\n )\n\n signature = dimo.auth.sign_challenge(\n message = challenge['challenge'],\n private_key = '<private_key>'\n )\n\n tokens = dimo.auth.submit_challenge(\n client_id = '<client_id>',\n domain = '<domain>',\n state = challenge['state'],\n signature = signature\n )\n```\n\n##### (Option 2) Auth Endpoint Shortcut Function\n\nAs mentioned earlier, this is the streamlined function call to directly get the `developer_jwt`. The `address` field in challenge generation is omitted since it is essentially the `client_id` of your application per Developer License:\n\n```python\nauth_header = dimo.auth.get_token(\n client_id = '<client_id>',\n domain = '<domain>',\n private_key = '<private_key>'\n)\n\n# Store the Developer JWT from the auth_header dictionary\ndev_jwt = auth_header[\"access_token\"]\n```\n\n### Querying the DIMO REST API\n\nThe SDK uses the [requests](https://requests.readthedocs.io/en/latest/) library for making HTTP requests. You can perform a query like so:\n\n```python\ndef decode_vin():\n device_makes = dimo.device_definitions.decode_vin(\n developer_jwt = dev_jwt,\n country_code = \"USA\",\n vin = \"<VIN>\"\n )\n # Do something with the response\n```\n\n#### Query Parameters\n\nFor query parameters, simply feed in an input that matches with the expected query parameters:\n\n```python\ndimo.device_definitions.search_device_definitions(\n query = \"Lexus gx 2023\"\n)\n```\n\n\n#### Vehicle JWTs\n\nAs the 2nd leg of the API authentication, applications may exchange for short-lived Vehicle JWTs for specific vehicles that granted privileges to the app. This uses the [DIMO Token Exchange API](https://docs.dimo.org/developer-platform/api-references/token-exchange-api).\n\nFor the end users of your application, they will need to share their vehicle permissions via the DIMO Mobile App or through your implementation of the [Login with DIMO flow](https://docs.dimo.org/developer-platform/getting-started/developer-guide/login-with-dimo). You can use the pre-built React component SDK, or redirect users to the URLs included in the documentation [here](https://docs.dimo.org/developer-platform/getting-started/developer-guide/login-with-dimo#dont-use-react).\n\nTypically, any endpoints that uses a NFT `tokenId` in path parameters will require JWTs. You can use this flow to obtain a privilege token.\n\n```python\n\nget_vehicle_jwt = dimo.token_exchange.exchange(\n developer_jwt = dev_jwt, \n # The Developer JWT you received using either the three step function calls, or the .get_token() shortcut \n privileges=[1, 3, 4, 5],\n # The privileges you've set for this vehicle, in list format (e.g. [1, 3, 4, 5])\n token_id=\"<token_id>\" \n # The Vehicle NFT Token ID that you are requesting permission to\n )\nvehicle_jwt = get_vehicle_jwt['token']\n```\n\nOnce you have the privilege token, you can pipe it through to corresponding endpoints like so:\n\n```python\ndef my_trips():\n trip_data = dimo.trips.trips(\n vehicle_jwt=vehicle_jwt, \n token_id=<token_id>\n )\n return trip_data\n```\n\n### Querying the DIMO GraphQL API\n\nThe SDK accepts any type of valid custom GraphQL queries, but we've also included a few sample queries to help you understand the DIMO GraphQL APIs.\n\n#### Authentication for GraphQL API\n\nThe GraphQL entry points are designed almost identical to the REST API entry points. For any GraphQL API that requires auth headers (Telemetry API for example), you can use the same pattern as you would in the REST protected endpoints.\n\n```python\n\ntelemetry_data = dimo.telemetry.query(\n vehicle_jwt=vehicle_jwt,\n query= \"\"\"\n query {\n some_valid_GraphQL_query\n }\n \"\"\"\n )\n```\n\n#### Send a custom GraphQL query\n\nTo send a custom GraphQL query, you can simply call the `query` function on any GraphQL API Endpoints and pass in any valid GraphQL query. To check whether your GraphQL query is valid, please visit our [Identity API GraphQL Playground](https://identity-api.dimo.zone/) or [Telemetry API GraphQL Playground](https://telemetry-api.dimo.zone/).\n\n```python\nmy_query = \"\"\"\n {\n vehicles (first:10) {\n totalCount\n }\n }\n \"\"\"\n\ntotal_network_vehicles = dimo.identity.query(query=my_query)\n```\n\n## How to Contribute to the SDK\n\nYou can read more about contributing [here](https://github.com/DIMO-Network/dimo-python-sdk/blob/dev-barrettk/CONTRIBUTING.md)\n",
"bugtrack_url": null,
"license": null,
"summary": "DIMO SDK in Python",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/DIMO-Network/dimo-python-sdk",
"Issues": "https://github.com/DIMO-Network/dimo-python-sdk/issues"
},
"split_keywords": [
"dimo",
" sdk",
" python",
" depin",
" web3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ef6e2e6240802a81b5d4ca805fd3d67c080165893c2a3f0499ca0aa9cfa43f58",
"md5": "882d07cf3f5577ab609e50184563f381",
"sha256": "bd7b1ac3a88b3d50920f5afa832635cfc7c0e7f433d477abfb3642104db7f418"
},
"downloads": -1,
"filename": "dimo_python_sdk-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "882d07cf3f5577ab609e50184563f381",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18170,
"upload_time": "2024-12-20T15:27:32",
"upload_time_iso_8601": "2024-12-20T15:27:32.587085Z",
"url": "https://files.pythonhosted.org/packages/ef/6e/2e6240802a81b5d4ca805fd3d67c080165893c2a3f0499ca0aa9cfa43f58/dimo_python_sdk-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb18caaf3e53e88288c2364def1b4b5b66e1a245e1ec021add00e9a5dcd02bc1",
"md5": "941316c17fedbdd69b63fab5a267e78e",
"sha256": "65e2b8e1238ddf13ce850caf84fed123d68bf590b7ec008661185ed13d49f8b0"
},
"downloads": -1,
"filename": "dimo_python_sdk-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "941316c17fedbdd69b63fab5a267e78e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16876,
"upload_time": "2024-12-20T15:27:35",
"upload_time_iso_8601": "2024-12-20T15:27:35.119609Z",
"url": "https://files.pythonhosted.org/packages/bb/18/caaf3e53e88288c2364def1b4b5b66e1a245e1ec021add00e9a5dcd02bc1/dimo_python_sdk-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 15:27:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DIMO-Network",
"github_project": "dimo-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.30.0"
]
]
},
{
"name": "python-dotenv",
"specs": []
},
{
"name": "eth-account",
"specs": [
[
"==",
"0.13.4"
]
]
},
{
"name": "eth-utils",
"specs": [
[
"==",
"4.1.1"
]
]
}
],
"lcname": "dimo-python-sdk"
}
JSON
