|
| 1 | +# Tune Insight Python SDK |
| 2 | + |
| 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 | + |
| 5 | +## Documentation |
| 6 | + |
| 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 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +The SDK is available on `pip`: |
| 12 | + |
| 13 | +```bash |
| 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 | +If the instance you are trying to reach is in a secure environment, you might need to access it through a proxy. Enter the URL of your proxy as `http_proxy` and `https_proxy` parameters of `Diapason.from_config`. Most of the time, these will be the same value. |
| 65 | + |
| 66 | +```python |
| 67 | +client = Diapason.from_config( |
| 68 | + api_url="<api_url>/api", # The url of the Tune Insight API to which the client will connect. |
| 69 | + oidc_client_id="<frontend_client_id>", # This is the front client id given by Tune Insight in the Portal. |
| 70 | + http_proxy="http://url/of/proxy:port", # URL of the proxy to use for HTTP requests (often http://localhost:port). |
| 71 | + https_proxy="http://url/of/proxy:port", # URL of the proxy to use for HTTPS requests (usually the same as http_proxy). |
| 72 | +) |
| 73 | +``` |
| 74 | + |
| 75 | +## Troubleshooting |
| 76 | + |
| 77 | +#### command not found: test-ti-install |
| 78 | + |
| 79 | +The installation of the package did not work, or a version before `0.14.0` was installed. To check the installed version, run the following line in the terminal: |
| 80 | + |
| 81 | +```bash |
| 82 | +pip freeze | grep tuneinsight |
| 83 | +``` |
| 84 | + |
| 85 | +The result should look like this: |
| 86 | + |
| 87 | +``` |
| 88 | +tuneinsight==1.0.0 |
| 89 | +``` |
| 90 | + |
| 91 | +If you see a line that looks like this, |
| 92 | + |
| 93 | +``` |
| 94 | +tuneinsight @ file:///path/to/file/tuneinsight-0.13.1-py3-none-any.whl#sha256=... |
| 95 | +``` |
| 96 | + |
| 97 | +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`: |
| 98 | + |
| 99 | +`pip install tuneinsight==1.0.0` |
| 100 | + |
| 101 | +#### Error: Could not load the cryptolib: contact your administrator. |
| 102 | + |
| 103 | +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. |
| 104 | + |
| 105 | +This issue should also trigger a warning to help identify the cause. |
| 106 | + |
| 107 | +- `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. |
| 108 | +- `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]). |
| 109 | +- `/lib/.../libc.so: version 'GLIBC_2.32' not found`: you need to install [`libc`](https://www.gnu.org/software/libc/) at the appropriate version (`2.32` in this case) on the machine that runs the SDK (potentially, a Docker container). |
| 110 | + |
| 111 | +#### Client is not allowed to initiate OAuth 2.0 Device Authorization Grant. |
| 112 | + |
| 113 | +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: |
| 114 | + |
| 115 | +- The `frontend_client_id` you entered is not correct. |
| 116 | +- Your Python environment can't connect to the authentication provider (https://auth.tuneinsight.com) |
| 117 | +- The authentication configuration does not allow the use of the SDK. Contact your administrator. |
| 118 | +- 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). |
| 119 | + |
| 120 | +#### `client.login` hangs for some time after entering credentials. |
| 121 | + |
| 122 | +This means that the login was successful, 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: |
| 123 | + |
| 124 | +``` |
| 125 | +httpx.ConnectError: [Errno -3] Temporary failure in name resolution |
| 126 | +``` |
| 127 | + |
| 128 | +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 (wrong URL, client ID, or proxy configuration). |
| 129 | + |
| 130 | +#### API version mismatch: the server and client use different versions of the API. |
| 131 | + |
| 132 | +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. |
| 133 | +Depending on the versions, this might not be too big of an issue, but it is strongly recommended to install the same version. |
| 134 | +Ask your administrator for the version installed on the Tune Insight instance, and install the corresponding SDK version with |
| 135 | + |
| 136 | +```bash |
| 137 | +pip install tuneinsight==0.xx.y |
| 138 | +``` |
| 139 | + |
| 140 | +## License |
| 141 | + |
| 142 | +Apache License 2.0 |
0 commit comments