You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Diapason is the official Python SDK for the Tune Insight API.
33
+
This is the official Python SDK for the Tune Insight API. It can be used to interface with a Tune Insight instance. The SDK enables programmatic use of Tune Insight from Jupyter notebooks and integration with other softwares, and gives access to advanced features such as custom preprocessing algorithms and machine learning pipelines.
33
34
34
35
## Documentation
35
36
36
-
Please refer to the [official documentation](https://dev.tuneinsight.com/docs/Usage/python-sdk/) for a detailed explanation on how to use Diapason.
37
+
The [official documentation](https://dev.tuneinsight.com/docs/Usage/python-sdk/) gives a detailed explanation on how to use the SDK. The recommended starting point to learn how to use the SDK is with the [Quickstart notebook](https://github.com/tuneinsight/python-sdk/tree/main/examples/Quickstart.ipynb).
37
38
38
-
### Installing
39
+
## Installation
39
40
40
-
Download the latest version of the SDK at https://dev.tuneinsight.com/packages/tuneinsight-diapason-0.11.1.tar.gz, then install it using `pip`.
41
+
The SDK is available on `pip`:
41
42
42
43
```bash
43
-
pip install tuneinsight-diapason-11.1.0.tar.gz
44
+
pip install tuneinsight
45
+
```
46
+
47
+
If instructed by your administrator, you might need to install a specific version (e.g., `xx.y`):
48
+
49
+
```bash
50
+
pip install tuneinsight==xx.y
51
+
```
52
+
53
+
Note that versions `0.13.1` and older are not available on `pip`: [contact us]([email protected]) to get packages for these versions.
54
+
55
+
It is recommended to set up a custom environment for the SDK, e.g. using [`conda`](https://anaconda.org/anaconda/conda).
56
+
57
+
### Testing your implementation
58
+
59
+
After installing the package, run the following command in your terminal.
60
+
61
+
```bash
62
+
test-ti-install
63
+
```
64
+
65
+
If your installation succeeded, you should see the following message:
66
+
67
+
```
68
+
# Package is available ✅
69
+
# Cryptolib is available ✅
70
+
The Tune Insight SDK is correctly installed.
71
+
```
72
+
73
+
Refer to the [troubleshooting](#troubleshooting) section if you see any ❌.
74
+
75
+
### Connecting to a server
76
+
77
+
To further test your implementation, you can open a Python interpreter (e.g. a Jupyter notebook), and run the following commands, replacing `api_url` and `frontend_client_id` with the appropriate values. This will open a browser window asking you to log in to your Tune Insight account.
78
+
79
+
```python
80
+
from tuneinsight import Diapason
81
+
82
+
client = Diapason.from_config(
83
+
api_url="<api_url>/api", # The url of the Tune Insight API to which the client will connect.
84
+
oidc_client_id="<frontend_client_id>", # This is the front client id given by Tune Insight in the Portal.
85
+
)
86
+
87
+
client.login()
88
+
89
+
client.healthcheck(error=True)
90
+
```
91
+
92
+
If all goes well, this should complete in a few seconds (after you have entered your login details). You now have everything you need to start using the SDK! The recommended next step is to run the [Quickstart notebook](https://github.com/tuneinsight/python-sdk/tree/main/examples/Quickstart.ipynb) to learn more about existing features.
93
+
94
+
## Troubleshooting
95
+
96
+
#### command not found: test-ti-install
97
+
98
+
The installation of the package did not work, or a version before `0.14.0.1` was installed. To check the installed version, run the following line in the terminal:
the SDK was installed directly from a `.whl` file, suggesting you are using an older version. You might need to install a more recent version, using `pip`:
117
+
118
+
`pip install tuneinsight==0.14.0`
119
+
120
+
#### Error: Could not load the cryptolib: contact your administrator.
121
+
122
+
This means that the installation succeeded, but the `cryptolib` module of the SDK could not be installed on your system. You can still use your installation, but some features will not be available.
123
+
124
+
This issue should also trigger a warning to help identify the cause.
125
+
126
+
- `Could not find the cryptolib library. Your platform might not be supported.`: this means that the precompiled binary of the cryptolib is not available, most likely because it was not compiled for your operating system and architecture. The SDK is available for all common OSes and architectures, but we can compile for additional architectures if necessary.
127
+
- `cannot open shared object file: ...`: the precompiled binary was found, but it could not be loaded by your system. This issue could be caused by a number of issues, so we suggest [reaching out to us]([email protected]).
128
+
129
+
#### Client is not allowed to initiate OAuth 2.0 Device Authorization Grant.
130
+
131
+
This error (which occurs when running `client.login`) suggests that the client or instance is not properly configured. Usually, this is caused by one of the following:
132
+
133
+
- The `frontend_client_id` you entered is not correct.
134
+
- Your Python environment can't connect to the authentication provider (https://auth.tuneinsight.com)
135
+
- The authentication configuration does not allow the use of the SDK. Contact your administrator.
136
+
- Your instance uses a different authentication provider. You will need to change the `oidc_url` argument in `Diapason.from_config`. Ask your administrator for the url that you should use (don't forget the `/auth/` at the end of the URL).
137
+
138
+
#### `client.login` hangs for some time after entering credentials.
139
+
140
+
This means that the login was succesful, but the client is not able to connect to the Tune Insight instance. An error message will typically appear after a minute or so. If you get the following error, it might just be that the `api_url` you entered was not correct:
141
+
142
+
```
143
+
httpx.ConnectError: [Errno -3] Temporary failure in name resolution
144
+
```
145
+
146
+
For other errors, contact your administrator: this might suggest that the instance is down or otherwise unavailable, or that there was an issue with the configuration.
147
+
148
+
#### API version mismatch: the server and client use different versions of the API.
149
+
150
+
This warning will not occur during the test script, but commonly occurs when using the SDK (specifically, creating or connecting to a project). It means that the version you installed is not consistent with the version of the Tune Insight instance you are connecting to.
151
+
Depending on the versions, this might not be too big of an issue, but it is strongly recommended to install the same version.
152
+
Ask your administrator for the version installed on the Tune Insight instance, and install the corresponding SDK version with
Copy file name to clipboardExpand all lines: README.md
+116-5
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,128 @@
1
1
# Tune Insight Python SDK
2
2
3
-
Diapason is the official Python SDK for the Tune Insight API.
3
+
This is the official Python SDK for the Tune Insight API. It can be used to interface with a Tune Insight instance. The SDK enables programmatic use of Tune Insight from Jupyter notebooks and integration with other softwares, and gives access to advanced features such as custom preprocessing algorithms and machine learning pipelines.
4
4
5
5
## Documentation
6
6
7
-
Please refer to the [official documentation](https://dev.tuneinsight.com/docs/Usage/python-sdk/)for a detailed explanation on how to use Diapason.
7
+
The [official documentation](https://dev.tuneinsight.com/docs/Usage/python-sdk/)gives a detailed explanation on how to use the SDK. The recommended starting point to learn how to use the SDK is with the [Quickstart notebook](https://github.com/tuneinsight/python-sdk/tree/main/examples/Quickstart.ipynb).
8
8
9
-
### Installing
9
+
##Installation
10
10
11
-
Download the latest version of the SDK at https://dev.tuneinsight.com/packages/tuneinsight-diapason-0.14.0.tar.gz, then install it using `pip`.
11
+
The SDK is available on `pip`:
12
12
13
13
```bash
14
-
pip install tuneinsight-diapason-14.0.0.tar.gz
14
+
pip install tuneinsight
15
+
```
16
+
17
+
If instructed by your administrator, you might need to install a specific version (e.g., `xx.y`):
18
+
19
+
```bash
20
+
pip install tuneinsight==xx.y
21
+
```
22
+
23
+
Note that versions `0.13.1` and older are not available on `pip`: [contact us]([email protected]) to get packages for these versions.
24
+
25
+
It is recommended to set up a custom environment for the SDK, e.g. using [`conda`](https://anaconda.org/anaconda/conda).
26
+
27
+
### Testing your implementation
28
+
29
+
After installing the package, run the following command in your terminal.
30
+
31
+
```bash
32
+
test-ti-install
33
+
```
34
+
35
+
If your installation succeeded, you should see the following message:
36
+
37
+
```
38
+
# Package is available ✅
39
+
# Cryptolib is available ✅
40
+
The Tune Insight SDK is correctly installed.
41
+
```
42
+
43
+
Refer to the [troubleshooting](#troubleshooting) section if you see any ❌.
44
+
45
+
### Connecting to a server
46
+
47
+
To further test your implementation, you can open a Python interpreter (e.g. a Jupyter notebook), and run the following commands, replacing `api_url` and `frontend_client_id` with the appropriate values. This will open a browser window asking you to log in to your Tune Insight account.
48
+
49
+
```python
50
+
from tuneinsight import Diapason
51
+
52
+
client = Diapason.from_config(
53
+
api_url="<api_url>/api", # The url of the Tune Insight API to which the client will connect.
54
+
oidc_client_id="<frontend_client_id>", # This is the front client id given by Tune Insight in the Portal.
55
+
)
56
+
57
+
client.login()
58
+
59
+
client.healthcheck(error=True)
60
+
```
61
+
62
+
If all goes well, this should complete in a few seconds (after you have entered your login details). You now have everything you need to start using the SDK! The recommended next step is to run the [Quickstart notebook](https://github.com/tuneinsight/python-sdk/tree/main/examples/Quickstart.ipynb) to learn more about existing features.
63
+
64
+
## Troubleshooting
65
+
66
+
#### command not found: test-ti-install
67
+
68
+
The installation of the package did not work, or a version before `0.14.0.1` was installed. To check the installed version, run the following line in the terminal:
the SDK was installed directly from a `.whl` file, suggesting you are using an older version. You might need to install a more recent version, using `pip`:
87
+
88
+
`pip install tuneinsight==0.14.0`
89
+
90
+
#### Error: Could not load the cryptolib: contact your administrator.
91
+
92
+
This means that the installation succeeded, but the `cryptolib` module of the SDK could not be installed on your system. You can still use your installation, but some features will not be available.
93
+
94
+
This issue should also trigger a warning to help identify the cause.
95
+
96
+
-`Could not find the cryptolib library. Your platform might not be supported.`: this means that the precompiled binary of the cryptolib is not available, most likely because it was not compiled for your operating system and architecture. The SDK is available for all common OSes and architectures, but we can compile for additional architectures if necessary.
97
+
-`cannot open shared object file: ...`: the precompiled binary was found, but it could not be loaded by your system. This issue could be caused by a number of issues, so we suggest [reaching out to us]([email protected]).
98
+
99
+
#### Client is not allowed to initiate OAuth 2.0 Device Authorization Grant.
100
+
101
+
This error (which occurs when running `client.login`) suggests that the client or instance is not properly configured. Usually, this is caused by one of the following:
102
+
103
+
- The `frontend_client_id` you entered is not correct.
104
+
- Your Python environment can't connect to the authentication provider (https://auth.tuneinsight.com)
105
+
- The authentication configuration does not allow the use of the SDK. Contact your administrator.
106
+
- Your instance uses a different authentication provider. You will need to change the `oidc_url` argument in `Diapason.from_config`. Ask your administrator for the url that you should use (don't forget the `/auth/` at the end of the URL).
107
+
108
+
#### `client.login` hangs for some time after entering credentials.
109
+
110
+
This means that the login was succesful, but the client is not able to connect to the Tune Insight instance. An error message will typically appear after a minute or so. If you get the following error, it might just be that the `api_url` you entered was not correct:
111
+
112
+
```
113
+
httpx.ConnectError: [Errno -3] Temporary failure in name resolution
114
+
```
115
+
116
+
For other errors, contact your administrator: this might suggest that the instance is down or otherwise unavailable, or that there was an issue with the configuration.
117
+
118
+
#### API version mismatch: the server and client use different versions of the API.
119
+
120
+
This warning will not occur during the test script, but commonly occurs when using the SDK (specifically, creating or connecting to a project). It means that the version you installed is not consistent with the version of the Tune Insight instance you are connecting to.
121
+
Depending on the versions, this might not be too big of an issue, but it is strongly recommended to install the same version.
122
+
Ask your administrator for the version installed on the Tune Insight instance, and install the corresponding SDK version with
0 commit comments