Async support

.github/workflows/test.yml

@@ -16,10 +16,12 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install poetry==1.3.2
+        pip install poetry==2.2.1
         poetry config virtualenvs.create false
         poetry -vv install
+    - name: generate sync code
+      run: |
+        make generate-sync
     - name: Lint with black
       run: |
         black . --check

.gitignore

@@ -3,3 +3,8 @@
 **/.pytest_cache
 dist
 **/__pycache__
+kindwise/core.py
+kindwise/crop_health.py
+kindwise/insect.py
+kindwise/mushroom.py
+kindwise/plant.py

Makefile

@@ -1,3 +1,6 @@
+generate-sync:
+	python generate/generate_sync.py
+
 version-patch:
 	bump2version patch
 

README.md

@@ -25,6 +25,12 @@ If you want to use the router offline classifier:
 pip install kindwise-api-client[router]
 ```
 
+If you want to use async interface:
+
+```
+pip install kindwise-api-client[async]
+```
+
 ### API key
 
 The API key serves to identify your account and is required to make requests to the API. Get API key at
@@ -548,3 +554,37 @@ print(router.identify(image_path).simple)
 # }
 
 ```
+
+### Async Interface
+
+The same available methods are also available in async interface. Here is an example of how to use it.
+
+```python
+import asyncio
+from kindwise import AsyncPlantApi, PlantIdentification, UsageInfo
+
+async def main():
+    # initialize plant.id api
+    # "PLANT_API_KEY" environment variable can be set instead of specifying api_key
+    api = AsyncPlantApi(api_key='your_api_key')
+    # get usage information
+    usage: UsageInfo = await api.usage_info()
+
+    # identify plant by image
+    latitude_longitude = (49.20340, 16.57318)
+    # pass the image as a path
+    image_path = 'path/to/plant_image.jpg'
+    # make identification
+    identification: PlantIdentification = await api.identify(image_path, latitude_longitude=latitude_longitude)
+
+    # get identification by a token with changed views
+    # this method can be used to modify additional information in identification or to get identification from database
+    # also works with identification.custom_id
+    identification_with_different_views: PlantIdentification = await api.get_identification(identification.access_token)
+
+    # delete identification
+    await api.delete_identification(identification)  # also works with identification.access_token or identification.custom_id
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```

README_internal.md

@@ -3,15 +3,43 @@
 ```bash
 conda env create
 conda activate kindowse-sdk
-poetry install
+pipx install poetry==2.2.1
+poetry install --extras router
 pre-commit install
 pre-commit install --hook-type commit-msg
+make generate-sync
 ```
 
+## Developmnet
+
+Do not directly modify files under `kindwise` directory. The ground truth code is located in `kindwise/async_api` directory. Use the following command to generate sync code from async code:
+
+```bash
+python generate/generate_sync_code.py
+# or
+make generate-sync
+```
 ## Tests
 
 Specify server used for testing via environmental variable `ENVIRONMENT`.
 
 - LOCAL: usually used for development on one system which is run locally
 - STAGING: default
 - PRODUCTION
+
+
+## Deployment
+
+```bash
+# Bump version
+#
+# if changes are not backward compatible, use "major"
+make version-major
+# if changes are backward compatible, use "minor" and some new features are added
+make version-minor
+# if only bug fixes, use "patch"
+make version-patch
+
+# Publish to PyPI
+make publish
+```

generate/generate_sync.py

@@ -0,0 +1,53 @@
+import unasync
+import os
+from pathlib import Path
+
+
+def post_process(filepath):
+    """
+    Manually fixes imports that unasync's token matching cannot handle.
+    """
+    with open(filepath, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # FIX 1: Rewrite the dotted import path
+    # Turns "from kindwise.async_api.core" -> "from kindwise.core"
+    content = content.replace("kindwise.async_api", "kindwise")
+
+    # FIX 2: Ensure any leftover relative imports are correct (if needed)
+    # content = content.replace("... something else ...", "...")
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def main():
+    gt_code_dir = Path(__file__).resolve().parent.parent / 'kindwise' / 'async_api'
+    filepaths = [path for path in gt_code_dir.glob('*.py') if path.stem != '__init__']
+    rules = [
+        unasync.Rule(
+            fromdir="/kindwise/async_api",
+            todir="/kindwise",
+            additional_replacements={
+                "AsyncClient": "Client",
+                "AsyncKindwiseApi": "KindwiseApi",
+                "anyio": "pathlib",
+                "AsyncInsectApi": "InsectApi",
+                "AsyncMushroomApi": "MushroomApi",
+                "AsyncCropHealthApi": "CropHealthApi",
+                "AsyncPlantApi": "PlantApi",
+            },
+        )
+    ]
+
+    filepaths_to_process = [os.path.abspath(p) for p in filepaths]
+    unasync.unasync_files(filepaths_to_process, rules)
+    generated_files = []
+    for path in filepaths:
+        dest_path = path.parent.parent / path.name
+        post_process(dest_path)
+        generated_files.append(str(dest_path))
+
+
+if __name__ == "__main__":
+    main()

kindwise/__init__.py

@@ -13,3 +13,7 @@
 from kindwise.mushroom import MushroomApi, MushroomKBType
 from kindwise.plant import HealthAssessment, PlantApi, PlantIdentification, PlantKBType, RawPlantIdentification
 from kindwise.router import Router, RouterSize
+from kindwise.async_api.crop_health import AsyncCropHealthApi
+from kindwise.async_api.insect import AsyncInsectApi
+from kindwise.async_api.mushroom import AsyncMushroomApi
+from kindwise.async_api.plant import AsyncPlantApi