UncountablePythonSDK 0.0.21__py3-none-any.whl → 0.0.23__py3-none-any.whl

{UncountablePythonSDK-0.0.21.dist-info → UncountablePythonSDK-0.0.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: UncountablePythonSDK
-Version: 0.0.21
+Version: 0.0.23
 Summary: Uncountable SDK
 Project-URL: Homepage, https://github.com/uncountableinc/uncountable-python-sdk
 Project-URL: Repository, https://github.com/uncountableinc/uncountable-python-sdk.git

{UncountablePythonSDK-0.0.21.dist-info → UncountablePythonSDK-0.0.23.dist-info}/RECORD

@@ -14,6 +14,7 @@ docs/static/favicons/favicon-32x32.png,sha256=U4UU652zGnSeU3P9kUqxPeEnVf6zhtdNdN
 docs/static/favicons/manifest.json,sha256=6q_3nZkcg_x0xut4eE-xpdeMY1TydwiZIcbXlLAq9X8,437
 docs/static/favicons/mstile-150x150.png,sha256=eAK4QdEofhdLtfmjuPTpnX3MJqYnvGXsHYUjlcQekyY,1035
 docs/static/favicons/safari-pinned-tab.svg,sha256=S84fRnz0ZxLnQrKtmmFZytiRyu1xLtMR_RVy5jmwU7k,1926
+examples/async_batch.py,sha256=wpf_3P547375vTIO4pKv5vw6WCkUnzqvw_S3idfhjvM,1122
 examples/create_entity.py,sha256=54AmZt83EpypxGcYZSIMmWlGz2oAgHFOsKuLSZOcHsI,625
 examples/upload_files.py,sha256=ZsMChgOioraVHv207YREpivAOf4dq3IxGIBoROoDX_4,482
 examples/recipe-import/importer.py,sha256=baD71xuNibxDTe3bGHsMEIZEf9Xtb-IumBNpCEV0RZU,1134
@@ -34,16 +35,16 @@ pkgs/strenum_compat/__init__.py,sha256=wXRFeNvBm8RU6dy1PFJ5sRLgUIEeH_DVR95Sv5qpG
 pkgs/strenum_compat/strenum_compat.py,sha256=uOUAgpYTjHs1MX8dG81jRlyTkt3KNbkV_25zp7xTX2s,36
 pkgs/type_spec/__init__.py,sha256=h5DmJTca4QVV10sZR1x0-MlkZfuGYDfapR3zHvXfzto,19
 pkgs/type_spec/__main__.py,sha256=5bJaX9Y_-FavP0qwzhk-z-V97UY7uaezJTa1zhO_HHQ,1048
-pkgs/type_spec/builder.py,sha256=W9VA7JhPkLw3lau3FjYlIiBGzRs5LBPTZr0tTO2KVuU,39570
+pkgs/type_spec/builder.py,sha256=9fEcZkasqovH8W4PtQvXtPu4psS_a-HAyu6Wsfk5L8w,43041
 pkgs/type_spec/config.py,sha256=INfEiDcUsZFUKasHprsE6i33siPB0RnfmTKOsWcGnQ8,5043
-pkgs/type_spec/emit_io_ts.py,sha256=gCEfS81w_ifqjLVJ3_cpy9Gq03o6H5nEsh35WAkqGGE,5606
-pkgs/type_spec/emit_open_api.py,sha256=4ihGO_neLL1A9zdoytQ5YypgBqyM0WKzBHo9wtsBPuE,17772
-pkgs/type_spec/emit_open_api_util.py,sha256=gMUB-fSrnTp6NyK_HbY02SP6cqSRObo-KIojDu4rn44,1900
-pkgs/type_spec/emit_python.py,sha256=CCHlOIMKdGu1VoaP7ly6dZ2cYank9jaAr8NDN50rFiE,42411
-pkgs/type_spec/emit_typescript.py,sha256=KOCcPuwSLRSt3pIp06Nq9exledq-kWtrA4RnUpeGMi8,17505
+pkgs/type_spec/emit_io_ts.py,sha256=Ghd8XYqyNYldHQDepwa9GLfHXcoi48ztBw84K28ETic,5707
+pkgs/type_spec/emit_open_api.py,sha256=RJzzOZ7Ti1PNTPn42ZGW7OA6L9KRQhKOTw4elXzJKpE,23524
+pkgs/type_spec/emit_open_api_util.py,sha256=F6qouGVm2-WGYkoubbBtRu00V4e30bWJ0fDBhigBEfg,2248
+pkgs/type_spec/emit_python.py,sha256=aGPnp86DZN0N7c5eiBHVAT_smDf1uCLmRldDhxmWx9g,42673
+pkgs/type_spec/emit_typescript.py,sha256=4hpCJwiDf-v8LJaNFVfFtf8zvtG73YNPFwwa_5NuffI,17729
 pkgs/type_spec/emit_typescript_util.py,sha256=93FzJnpYse4PKFzgdw4DGV4zFTi5tF4WR-CIi7cW498,873
-pkgs/type_spec/load_types.py,sha256=AB334CF-368dpMNXE2QIFT7WxESvuew2RK_GG2MREng,2211
-pkgs/type_spec/open_api_util.py,sha256=88zgI_lHi6SjCaNfKpoiCjd1o0Npysjk-7iCXw0a3Hs,7463
+pkgs/type_spec/load_types.py,sha256=xEHwdB_miR3vNs161Oy1luafE0VC-yk9-utAyCJmbEo,3629
+pkgs/type_spec/open_api_util.py,sha256=TFbK2bkYT6S4qPQGO3_G2mfVgtNB26d31kwaHQ9y99E,6730
 pkgs/type_spec/test.py,sha256=4ueujBq-pEgnX3Z69HyPmD-bullFXmpixcpVzfOkhP4,489
 pkgs/type_spec/util.py,sha256=6m6MPfY-SwjyZf2FWQKclswWB5o7gcdd-3tdpViPYOQ,4844
 pkgs/type_spec/actions_registry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -61,8 +62,8 @@ pkgs/type_spec/value_spec/types.py,sha256=a2zxbbCRWepY1l8OtjeCDKgBKFPFHVgV99oP6p
 type_spec/external/api/batch/execute_batch.yaml,sha256=gpdSev3sLEC_cMVSZdj-9bc_XDFDqdPdOII9Ojme2N8,1170
 type_spec/external/api/batch/execute_batch_load_async.yaml,sha256=gcn51NWLiSvlytz8k3_pDOVJLCGfdivKJPG4I9Q8CZc,435
 type_spec/external/api/chemical/convert_chemical_formats.yaml,sha256=EidTxMCRs-ko5yMFDptJPyAEWYZVruP41OG3cwyBLQQ,1069
-type_spec/external/api/entity/create_entities.yaml,sha256=NVA7I1b4xf81urMKaiaiQPgvykEvjKslfOAN2gOhMIE,1441
-type_spec/external/api/entity/create_entity.yaml,sha256=2itcDpiuZHckhn45ZJyrssMOS9_CgBwFGf-MQyUyImw,1636
+type_spec/external/api/entity/create_entities.yaml,sha256=RKjmb_iY4dVHf3aQUCU-OrlbTLLsCkULQ9uEfa8BMFY,1506
+type_spec/external/api/entity/create_entity.yaml,sha256=Orz-3RZsNy5cWXlA3BKVQDYGnGGXlCXOtsOxDSm_nRY,1701
 type_spec/external/api/entity/get_entities_data.yaml,sha256=3XujG7bOpuBQlfFrYtG3L4fBk7LsmdSekmP9iU0zjF0,796
 type_spec/external/api/entity/list_entities.yaml,sha256=H2YVv6il-XVKd_7IipZqauTDvWCrvHok7z47bDH2sI4,1798
 type_spec/external/api/entity/resolve_entity_ids.yaml,sha256=Zf3OhAohwLJO7wWj0e-sK5lhIsXlD8A5Bu3OGjY4-tA,732
@@ -89,7 +90,7 @@ type_spec/external/api/recipes/associate_recipe_as_lot.yaml,sha256=8wzeJg5njt4qG
 type_spec/external/api/recipes/create_recipe.yaml,sha256=mGLyKJI3pN_7nU4rcSqCO3WjuKhO_odZ2pewVgYcMUU,1322
 type_spec/external/api/recipes/create_recipes.yaml,sha256=eXMlXRpB5TFt1mUTECBa4aAIG3KrxYT2mJ5vxmZ9Q3A,1503
 type_spec/external/api/recipes/disassociate_recipe_as_input.yaml,sha256=qTKQCNBNwLnbr22DQVLA6b80BdBhwnDbX1c4KoCKUm8,477
-type_spec/external/api/recipes/edit_recipe_inputs.yaml,sha256=CmolwyHSGJOQ33nJH7SQUYK-p2CWNEQ9yTstNxALv18,2631
+type_spec/external/api/recipes/edit_recipe_inputs.yaml,sha256=ljewBw77ucvl_m_KWmSJp-nVQGvVG6cb7xVOgPIlueU,2573
 type_spec/external/api/recipes/get_curve.yaml,sha256=zQpPwOYqojY-YwmTjbqoGtUxpYm3vne2sYpglWbPnpw,779
 type_spec/external/api/recipes/get_recipe_calculations.yaml,sha256=ZE7PzfWrjS7TiO4q7iyCwEj5In8GwO6fFIYGqUlTEXo,1240
 type_spec/external/api/recipes/get_recipe_links.yaml,sha256=Vwm0OVWl3VvDaI7chY_oZQqD8xZ1u09iFWKkZKn1ITo,766
@@ -103,8 +104,9 @@ type_spec/external/api/recipes/set_recipe_tags.yaml,sha256=IrdkbryxZjNy8n4aMNLRT
 type_spec/external/api/triggers/run_trigger.yaml,sha256=c8xDV3bQRjcRRDG4Y7kdQmMMu1fj3ae5eUi-Sdbsi54,405
 uncountable/__init__.py,sha256=281cC2hs8pbrD0jVKMol-tbWSh7Zcsc8oRT42dKteyE,102
 uncountable/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-uncountable/core/__init__.py,sha256=OYipeBMLl_Mk2LApzJqzvOWSyQ12tdOXURp1GsKSjyE,190
-uncountable/core/client.py,sha256=ebBwERBKbdp7x5y77bFeyyGejIi02fjFZ4AMCJUfMpA,4507
+uncountable/core/__init__.py,sha256=7xUnbSWJzS31sWg0jCe5nIksn5s0PVdwUrUmDttHfCY,258
+uncountable/core/async_batch.py,sha256=0cRmCr6Z9sNxZyfY9Dl8wlCA4anISVZuHGgBegHhUbc,749
+uncountable/core/client.py,sha256=7bLuACxMJZsckSfL2j-p-XThYdvDAUAwm5nND9s-v1o,6946
 uncountable/core/file_upload.py,sha256=zTpAFSd7_-TmEVWxOn1rDznyWE6_AdZyuDQC3LP34iI,2667
 uncountable/core/types.py,sha256=gQtCw1-WSRak_ypFlGI1Ea9iZBP9zDeFq6XQtiXBlZA,459
 uncountable/integration/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -119,19 +121,19 @@ uncountable/integration/db/connect.py,sha256=iI9e8a2hfbFP-dvH0MGLsrG-RpM0dHKCL-o
 uncountable/integration/executors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 uncountable/integration/executors/script_executor.py,sha256=6oMPAFe0PUdqt76e8jMi4vXszGVsVHLULob7Qbl3o38,816
 uncountable/types/__init__.py,sha256=fTNNsvFFkjp4acdBA8eS00OZVnDo_Zn7aRwPs8SFnrs,6024
-uncountable/types/async_batch.py,sha256=VMLB3ss1xzsFXovnWIaxgEVb4DWz7Agnf_MUNDaoRQc,1524
-uncountable/types/async_batch_processor.py,sha256=fwzfk0XY0L1ulzNi3dT8Aky5MyWPNK6GDStZ_I8Icoc,5914
+uncountable/types/async_batch.py,sha256=FtIoDCeyt9rF5hknQs6Sw-vjiYBMJbe1re0-4bk_6VY,1578
+uncountable/types/async_batch_processor.py,sha256=YksvTyJaZ3rqpZx4UXofUf7XU1Br4aNBNPZXB3LLtkA,5940
 uncountable/types/base.py,sha256=w3BRf8SAvYPlKrcJtJcQ_WhCU3A9zy0VuRTRWRFKVUA,2709
 uncountable/types/calculations.py,sha256=16J-KKMp-I8ZQUkYNmKCHfAn6DGb99cFinALcDIdGHY,562
 uncountable/types/chemical_structure.py,sha256=zQKl53DGtQQONIUHFXuwjWLQaG7FPZY7x6SBSOzkGV0,758
-uncountable/types/client_base.py,sha256=w-UnuzUSg8l_5kFhxo3w_b0_UC0eT-mtHheoA0f-U58,45967
+uncountable/types/client_base.py,sha256=nsV7NWN5UoqjCfFSw9XLXT_rbpfZeWRrOLxqeZ20Sjw,47114
 uncountable/types/curves.py,sha256=qYyRntMmFNonEwTrGhquMLbgMqjyP1moQflNTP0FMec,1308
 uncountable/types/entity.py,sha256=NjMZrqBwQ7sZe_oUuJqy9IEG7dWZmFMkQQXJ0_odcnA,11637
 uncountable/types/experiment_groups.py,sha256=ZBEk06F4n98Jz3oEA09WaDmw5rqPs7iVAm_Ysr4gc_o,599
 uncountable/types/field_values.py,sha256=2unBAeBqQPqLQKaL6nGpnDDksZ-5MZepgEF3sgy6oOk,1670
 uncountable/types/fields.py,sha256=eGtZ6axTYGFxLmPAyri2LwlcR4SZ2sX2c6QDX0ybKz0,570
 uncountable/types/id_source.py,sha256=Y3suURq3L1SahZ2oHPD986SU0l3Ik-ZzH38aQKgc1Fg,1341
-uncountable/types/identifier.py,sha256=O_J3sHsG3pFeSIxUKmgIK97FZl6f4qkRDwsNLvY7ymE,1389
+uncountable/types/identifier.py,sha256=94-O3H_qNrA48tf3srwPwdu8HURkLl7_-88kUnwElZg,1455
 uncountable/types/input_attributes.py,sha256=u-JABoZ-Ij1Ynq5g6MxOgRdQeYbM7OnGP2q_N7KuVdw,826
 uncountable/types/inputs.py,sha256=q7fNGaSKIk3R6uXCEhSQpiHvXu82YcK3oZHDI7bxE88,1597
 uncountable/types/outputs.py,sha256=hSUlu41sisYKIZpPrj1G1DRfKm6hsKNcd1eNKFYb-4w,671
@@ -144,7 +146,7 @@ uncountable/types/recipe_links.py,sha256=RldSV7SdeBYa0bx02DzMg4jfPdgrlMRE40T16Fd
 uncountable/types/recipe_metadata.py,sha256=cebGg_lJzqZzGnKnDgmuQFrw4Xhoz6HEiGM6G0az120,1437
 uncountable/types/recipe_output_metadata.py,sha256=XJA8R1r4NTzyR_DhMkmH4ZtYD-vqpvBMji9Be8OcFmo,613
 uncountable/types/recipe_tags.py,sha256=lYpksHAxXCcIjZKR7JoZOTH2cBSovwxZaHwjZy_yqiQ,581
-uncountable/types/recipe_workflow_steps.py,sha256=bHVkwlsGODLpRFMJ2Ja-5FV1kqYjed8J0J0gU1dmTLQ,2615
+uncountable/types/recipe_workflow_steps.py,sha256=LmyFwWWwJv30vuaQ4qtd0hzDdeJaIxHQZqwRb1Wi_6A,2626
 uncountable/types/response.py,sha256=ZI0CG7ZxBM2k5_W-6mNMU3UlB0p1i-0nrwOvsMaS-vU,620
 uncountable/types/units.py,sha256=_kZ7KkXIbRiY2fOdkTsbJBpWRah5TCC2WWiG05e-1DA,565
 uncountable/types/users.py,sha256=SUjNHBDcImKnnE7IN096Wfr1fmjNjCkQ7yQgKUPffz8,588
@@ -156,8 +158,8 @@ uncountable/types/api/batch/execute_batch_load_async.py,sha256=dcdGFibO8fUDpC__X
 uncountable/types/api/chemical/__init__.py,sha256=gCgbynxG3jA8FQHzercKtrHKHkiIKr8APdZYUniAor8,55
 uncountable/types/api/chemical/convert_chemical_formats.py,sha256=COGzkfpTL_Ermg2cbasoVKGAxDAtJaTFay18IZtrWCA,1305
 uncountable/types/api/entity/__init__.py,sha256=gCgbynxG3jA8FQHzercKtrHKHkiIKr8APdZYUniAor8,55
-uncountable/types/api/entity/create_entities.py,sha256=oZVBovL3pdBfoKpaOXJcPtUyDxjKgFnYEqKfGx_ZcvE,1649
-uncountable/types/api/entity/create_entity.py,sha256=J6eY8b_XEQROFR7FI7In3zmFngaCBY5TcasMi4wy9t8,1819
+uncountable/types/api/entity/create_entities.py,sha256=vzo5hS1qcmjQdfyCMarSu8MRcRGSiholOVSCfjXlA1k,1703
+uncountable/types/api/entity/create_entity.py,sha256=ausozCQ3qPM9YUQ87bOTCKOm-zkhn4CSLJr9jLc9n2U,1873
 uncountable/types/api/entity/get_entities_data.py,sha256=XjrJGZucIn1TYUlDLRnRA0JTQw-vXHIAT-m0H9hk37A,1170
 uncountable/types/api/entity/list_entities.py,sha256=_bIIZJj3N0E6YiHgqzfCOKxD1fQW6biWJQMp5wIVbBw,1514
 uncountable/types/api/entity/resolve_entity_ids.py,sha256=AidGpPmI9ATDv0E7vd9LDOl3n3beGxUlRojh5uZrkl4,1086
@@ -193,7 +195,7 @@ uncountable/types/api/recipes/associate_recipe_as_lot.py,sha256=bTYjbnY3B7GKz4MV
 uncountable/types/api/recipes/create_recipe.py,sha256=Ni00efkcPkQ3WTIgDHzkfu1qoc52ReV9VT0wwwPOT4g,1364
 uncountable/types/api/recipes/create_recipes.py,sha256=qwIYa8hfcjY7_VOFt9lxmVtJ-HOJqQN3GDNSbZsRCZU,1544
 uncountable/types/api/recipes/disassociate_recipe_as_input.py,sha256=L25fpiK1Y5PByPVVgsZy9t4podz3xSSLIwKHj8CUrSg,913
-uncountable/types/api/recipes/edit_recipe_inputs.py,sha256=Ae7YMUsONp1bUVdaznetWiw-THPndnzFI-t4iMWV_eg,3338
+uncountable/types/api/recipes/edit_recipe_inputs.py,sha256=pTw606AgLhb-oJjfj1WPyEcJ4B0tgZsvEKeqP5VZ1gY,3281
 uncountable/types/api/recipes/get_curve.py,sha256=UIWfpqtU5sQokaxwYfQFNFl6HMyzWEF_Sjd8UMz0U88,939
 uncountable/types/api/recipes/get_recipe_calculations.py,sha256=eQmkdZzCEuq8S2f_kf_7GPvDLX1pTnY1CRmkK0SkMCI,1472
 uncountable/types/api/recipes/get_recipe_links.py,sha256=hk5dfQjv7yU2r-S9b8vwWEJLPHqU0-M6SFiTLMR3fVk,985
@@ -206,7 +208,7 @@ uncountable/types/api/recipes/set_recipe_outputs.py,sha256=QYq39TNchQ80ET1C77OE9
 uncountable/types/api/recipes/set_recipe_tags.py,sha256=U710hgq9-t6QZGRB-ZGHskpt4iXwYEjIRb67eh3P518,2453
 uncountable/types/api/triggers/__init__.py,sha256=gCgbynxG3jA8FQHzercKtrHKHkiIKr8APdZYUniAor8,55
 uncountable/types/api/triggers/run_trigger.py,sha256=9m9M8-nlGB_sAU2Qm2lWugp4h4Osqj6QpjNfU8osd1U,901
-UncountablePythonSDK-0.0.21.dist-info/METADATA,sha256=_xqCDeMHkCp6YfUDs-Wr2wc7e2ErYtHzjA1f6YqcGfc,1613
-UncountablePythonSDK-0.0.21.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-UncountablePythonSDK-0.0.21.dist-info/top_level.txt,sha256=HaMiBnH1wA7SG9-RVHIJPBH3l8X5gee2jUf-77Nz-Dk,41
-UncountablePythonSDK-0.0.21.dist-info/RECORD,,
+UncountablePythonSDK-0.0.23.dist-info/METADATA,sha256=W6CHPkwSSSiPK9zlnXFS8WjX7sCL8o2-76dd4m2CJkY,1613
+UncountablePythonSDK-0.0.23.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+UncountablePythonSDK-0.0.23.dist-info/top_level.txt,sha256=HaMiBnH1wA7SG9-RVHIJPBH3l8X5gee2jUf-77Nz-Dk,41
+UncountablePythonSDK-0.0.23.dist-info/RECORD,,

examples/async_batch.py

@@ -0,0 +1,36 @@
+from decimal import Decimal
+from uncountable.core import AuthDetailsApiKey, Client
+from uncountable.core import AsyncBatchProcessor
+from uncountable.types import (
+    recipe_metadata,
+)
+from uncountable.types.identifier import IdentifierKeyBatchReference
+from uncountable.types.recipe_identifiers import (
+    RecipeIdentifierEditableName,
+    RecipeIdentifiers,
+)
+
+
+client = Client(
+    base_url="https://app.uncountable.com",
+    auth_details=AuthDetailsApiKey(
+        api_id="X",
+        api_secret_key="X",
+    ),
+)
+batch_loader = AsyncBatchProcessor(client=client)
+recipe_identifiers: RecipeIdentifiers = []
+recipe_identifiers.append(
+    RecipeIdentifierEditableName(editable_name="My recipe from API")
+)
+req = batch_loader.create_recipe(
+    material_family_id=1, workflow_id=1, identifiers=recipe_identifiers
+)
+created_recipe_reference = req.batch_reference
+batch_loader.set_recipe_metadata(
+    recipe_key=IdentifierKeyBatchReference(reference=created_recipe_reference),
+    recipe_metadata=[
+        recipe_metadata.MetadataValue(metadata_id=7, value_numeric=Decimal(38))
+    ],
+)
+job_id = batch_loader.send()

pkgs/type_spec/builder.py

@@ -10,7 +10,7 @@ import re
 from collections import defaultdict
 from dataclasses import MISSING, dataclass
 from enum import Enum, StrEnum, auto
-from typing import Any, Optional
+from typing import Any, Optional, Self
 
 from . import util
 from .util import parse_type_str, unused
@@ -86,6 +86,7 @@ class BaseTypeName(StrEnum):
     s_optional = "Optional"
     s_string = "String"
     s_tuple = "Tuple"
+    s_readonly_array = "ReadonlyArray"
     s_union = "Union"
 
     # For a root class that defines properties
@@ -184,6 +185,34 @@ class SpecTypeInstance(SpecType):
         return defn_type + self.parameters
 
 
+@dataclass(kw_only=True)
+class SpecEndpointExample:
+    summary: str
+    description: str
+    arguments: dict[str, object]
+    data: dict[str, object]
+
+
+@dataclass(kw_only=True)
+class SpecGuide:
+    title: str
+    markdown_content: str
+    html_content: str
+
+
+@dataclass(kw_only=True, frozen=True)
+class RootGuideKey:
+    pass
+
+
+@dataclass(kw_only=True, frozen=True)
+class EndpointGuideKey:
+    path: str
+
+
+SpecGuideKey = RootGuideKey | EndpointGuideKey
+
+
 class SpecTypeLiteralWrapper(SpecType):
     def __init__(
         self,
@@ -672,6 +701,32 @@ class ResultType(StrEnum):
 RE_ENDPOINT_ROOT = re.compile(r"\${([_a-z]+)}")
 
 
+@dataclass(kw_only=True, frozen=True)
+class _EndpointPathDetails:
+    root: str
+    root_path: str
+    resolved_path: str
+
+
+def _resolve_endpoint_path(
+    path: str, api_endpoints: dict[str, str]
+) -> _EndpointPathDetails:
+    root_path_source = path.split("/")[0]
+    root_match = RE_ENDPOINT_ROOT.fullmatch(root_path_source)
+    if root_match is None:
+        raise Exception(f"invalid-api-path-root:{root_path_source}")
+
+    root_var = root_match.group(1)
+    root_path = api_endpoints[root_var]
+
+    _, *rest_path = path.split("/", 1)
+    resolved_path = "/".join([root_path] + rest_path)
+
+    return _EndpointPathDetails(
+        root=root_var, root_path=root_path, resolved_path=resolved_path
+    )
+
+
 class SpecEndpoint:
     method: RouteMethod
     root: str
@@ -748,14 +803,10 @@ class SpecEndpoint:
 
         self.result_type = ResultType(data.get("result_type", ResultType.json.value))
 
+        path_details = _resolve_endpoint_path(data["path"], builder.api_endpoints)
+        self.root = path_details.root
+        self.path_root = path_details.root_path
         self.desc = data.get("desc")
-
-        root_match = RE_ENDPOINT_ROOT.fullmatch(path[0])
-        if root_match is None:
-            raise Exception(f"invalid-api-path-root:{path[0]}")
-
-        self.root = root_match.group(1)
-        self.path_root = builder.api_endpoints[self.root]
         # IMPROVE: remove need for is_external flag
         self.is_external = self.path_root == "api/external"
         self.has_attachment = data.get("has_attachment", False)
@@ -764,6 +815,10 @@ class SpecEndpoint:
             not is_sdk or self.desc is not None
         ), f"Endpoint description required for SDK endpoints, missing: {path}"
 
+    @property
+    def resolved_path(self: Self) -> str:
+        return f"{self.path_root}/{self.path_dirname}/{self.path_basename}"
+
 
 def _parse_const(
     builder: SpecBuilder,
@@ -1014,6 +1069,8 @@ class SpecBuilder:
         self.pending: list[NamespaceDataPair] = []
         self.parts: dict[str, dict[str, str]] = defaultdict(dict)
         self.preparts: dict[str, dict[str, str]] = defaultdict(dict)
+        self.examples: dict[str, list[SpecEndpointExample]] = defaultdict(list)
+        self.guides: dict[SpecGuideKey, list[SpecGuide]] = defaultdict(list)
         self.api_endpoints = api_endpoints
         base_namespace = SpecNamespace(name=base_namespace_name)
         for base_type in BaseTypeName:
@@ -1198,5 +1255,53 @@ class SpecBuilder:
     def add_prepart_file(self, target: str, name: str, data: str) -> None:
         self.preparts[target][name] = data
 
+    def add_example_file(self, data: dict[str, object]) -> None:
+        path_details = _resolve_endpoint_path(str(data["path"]), self.api_endpoints)
+
+        examples_data = data["examples"]
+        if not isinstance(examples_data, list):
+            raise Exception(
+                f"'examples' in example files are expected to be a list, endpoint_path={path_details.resolved_path}"
+            )
+        for example in examples_data:
+            arguments = example["arguments"]
+            data_example = example["data"]
+            if not isinstance(arguments, dict) or not isinstance(data_example, dict):
+                raise Exception(
+                    f"'arguments' and 'data' fields must be dictionaries for each endpoint example, endpoint={path_details.resolved_path}"
+                )
+            self.examples[path_details.resolved_path].append(
+                SpecEndpointExample(
+                    summary=str(example["summary"]),
+                    description=str(example["description"]),
+                    arguments=arguments,
+                    data=data_example,
+                )
+            )
+
+    def add_guide_file(self, file_content: str) -> None:
+        import markdown
+
+        md = markdown.Markdown(extensions=["meta"])
+        html = md.convert(file_content)
+        meta: dict[str, list[str]] = md.Meta  # type: ignore[attr-defined]
+        title_meta: list[str] | None = meta.get("title")
+        if title_meta is None:
+            raise Exception("guides requier a title in the meta section")
+
+        path_meta: list[str] | None = meta.get("path")
+        guide_key: SpecGuideKey = RootGuideKey()
+        if path_meta is not None:
+            path_details = _resolve_endpoint_path("".join(path_meta), self.api_endpoints)
+            guide_key = EndpointGuideKey(path=path_details.resolved_path)
+
+        self.guides[guide_key].append(
+            SpecGuide(
+                title="".join(title_meta),
+                html_content=html,
+                markdown_content=file_content,
+            )
+        )
+
     def resolve_proper_name(self, stype: SpecTypeDefn) -> str:
         return f"{'.'.join(stype.namespace.path)}.{stype.name}"

pkgs/type_spec/emit_io_ts.py

@@ -118,7 +118,10 @@ def refer_to_io_ts(
     stype: builder.SpecType,
 ) -> str:
     if isinstance(stype, builder.SpecTypeInstance):
-        if stype.defn_type.name == builder.BaseTypeName.s_list:
+        if (
+            stype.defn_type.name == builder.BaseTypeName.s_list
+            or stype.defn_type.name == builder.BaseTypeName.s_readonly_array
+        ):
             spec = refer_to_io_ts(ctx, stype.parameters[0])
             return f"IO.array({spec})"
         if stype.defn_type.name == builder.BaseTypeName.s_union: