comotion-sdk 1.2.0__tar.gz → 1.2.2__tar.gz

{comotion_sdk-1.2.0 → comotion_sdk-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comotion-sdk
-Version: 1.2.0
+Version: 1.2.2
 Summary: SDK for interacting with the Comotion APIs
 Home-page: https://github.com/ComotionLabs/comotion-sdk
 Author: Comotion
@@ -67,6 +67,11 @@ pipenv install -e .
 pipenv shell
 ```
 
+When using nvim with basedpyright, start the editor from inside `pipenv shell`
+so the language server inherits the same Python environment. Type checking is
+configured in `pyproject.toml` and only covers hand-written code under
+`src/comotion/` and `tests/` (generated API clients are excluded).
+
 ## Adding modules
 
 
@@ -100,9 +105,16 @@ make html
 
 We use OpenApi generator to generate the python.
 
-The requirements for this are a swagger file that can be gotten from WHERE?
+There are two specifications, because the SDK talks to two different APIs:
 
-The latest swagger file is stored in openapi_generator/comodash_api_swagger.json
+| Spec | Generated package | API |
+| --- | --- | --- |
+| `openapi_generator/comodash_api_swagger.yaml` | `comodash_api_client_lowlevel` | Main Dash API, `https://{org}.api.comodash.io/v2` |
+| `openapi_generator/comodash_dailyrun_api_swagger.yaml` | `comodash_dailyrun_api_client_lowlevel` | DailyRun endpoints on the per-organisation frontend API, `https://api.{org}.comodash.io/superset` |
+
+They are generated independently, so regenerating one never touches the other.
+
+The requirements for this are a swagger file that can be gotten from WHERE?
 
 Download latest [jar of OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator#13---download-jar)
 
@@ -130,6 +142,54 @@ java -jar `
 
 We have changed from asyncio to urllib3 to ensure simplicity in coding without requiring "await" and "async"
 
+### Regenerating the DailyRun client
+
+The DailyRun client is generated the same way, from its own spec and into its own
+package. Note the different output directory: both generator runs would otherwise
+write `src/.openapi-generator/FILES`, `src/.openapi-generator/VERSION` and
+`src/.openapi-generator-ignore`, and the second run would overwrite the first
+run's copies of them. Generating into a scratch directory and copying only the
+package across keeps those shared files intact.
+
+```
+java -jar \
+  ./openapi_generator/openapi-generator-cli.jar generate \
+        -i ./openapi_generator/comodash_dailyrun_api_swagger.yaml\
+        -g python \
+        --package-name comodash_dailyrun_api_client_lowlevel \
+        --additional-properties \
+            generateSourceCodeOnly=True,library=urllib3 \
+        -o ./build/dailyrun_gen/
+
+cp -r build/dailyrun_gen/comodash_dailyrun_api_client_lowlevel src/
+cp build/dailyrun_gen/comodash_dailyrun_api_client_lowlevel_README.md src/
+rm -rf build
+```
+
+If you do not have a Java runtime, the generator also runs from its official
+Docker image. Pin the version so the output matches the existing clients:
+
+```
+docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli:v7.12.0 generate \
+        -i /local/openapi_generator/comodash_dailyrun_api_swagger.yaml \
+        -g python \
+        --package-name comodash_dailyrun_api_client_lowlevel \
+        --additional-properties generateSourceCodeOnly=True,library=urllib3 \
+        -o /local/build/dailyrun_gen/
+```
+
+After regenerating, check that the shared generator metadata is untouched:
+
+```
+git status src/.openapi-generator src/.openapi-generator-ignore
+```
+
+The hand-written `comotion.dash.DailyRun` class wraps this generated client and
+holds the behaviour the specification cannot express (scope checks, treating the
+`409` from `start_execution` as a normal result, the `verify` argument and the
+`GetDailyRunExecutionMode` enum). It lives in `src/comotion/`, which
+`src/.openapi-generator-ignore` excludes, so regenerating never discards it.
+
 To generate an html of the api:
 ```
 java -jar \