UncountablePythonSDK 0.0.83__py3-none-any.whl → 0.0.132__py3-none-any.whl

docs/conf.py

@@ -6,10 +6,15 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-from datetime import date
+import datetime
+
+from docutils import nodes  # type: ignore[import-untyped]
+from sphinx.addnodes import pending_xref  # type: ignore[import-not-found]
+from sphinx.application import Sphinx  # type: ignore[import-not-found]
+from sphinx.environment import BuildEnvironment  # type: ignore[import-not-found]
 
 project = "Uncountable SDK"
-copyright = f"{date.today().year}, Uncountable Inc"
+copyright = f"{datetime.datetime.now(tz=datetime.UTC).date().year}, Uncountable Inc"
 author = "Uncountable Inc"
 
 # -- General configuration ---------------------------------------------------
@@ -22,22 +27,23 @@ extensions = [
     "sphinx_copybutton",
     "sphinx_favicon",
 ]
-myst_enable_extensions = ["fieldlist", "deflist"]
+myst_enable_extensions = ["fieldlist", "deflist", "colon_fence"]
 
 autoapi_dirs = ["../uncountable"]
 autoapi_options = [
     "members",
+    "inherited-members",
     "undoc-members",
-    "show-inheritance",
-    "show-module-summary",
-    "imported-members",
 ]
+autoapi_root = "api"
 autoapi_ignore = ["*integration*"]
 autodoc_typehints = "description"
+autoapi_member_order = "groupwise"
+autoapi_own_page_level = "class"
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-
+python_use_unqualified_type_names = True
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -55,3 +61,44 @@ favicons = [
     "favicons/mstile-150x150.png",
     "favicons/safari-pinned-tab.svg",
 ]
+
+
+def _hook_missing_reference(
+    _app: Sphinx, _env: BuildEnvironment, node: pending_xref, contnode: nodes.Text
+) -> nodes.reference | None:
+    """
+    Manually resolve reference when autoapi reference resolution fails.
+    This is necessary because autoapi does not fully support type aliases.
+    """
+    # example reftarget value: uncountable.types.identifier_t.IdentifierKey
+    target = node.get("reftarget", "")
+
+    # example refdoc value: api/uncountable/types/generic_upload_t/GenericUploadStrategy
+    current_doc = node.get("refdoc", "")
+
+    if not target.startswith("uncountable"):
+        return None
+
+    target_module, target_name = target.rsplit(".", 1)
+
+    # construct relative path from current doc page to target page
+    relative_segments_to_root = [".." for _ in current_doc.split("/")]
+    relative_segments_to_target = target_module.split(".")
+
+    # example full relative path: ../../../../../api/uncountable/types/identifier_t/#uncountable.types.identifier_t.IdentifierKey
+    full_relative_path = "/".join([
+        *relative_segments_to_root,
+        autoapi_root,
+        *relative_segments_to_target,
+        f"#{target}",
+    ])
+
+    return nodes.reference(
+        text=target_name if python_use_unqualified_type_names else target,
+        children=[contnode],
+        refuri=full_relative_path,
+    )
+
+
+def setup(app: Sphinx) -> None:
+    app.connect("missing-reference", _hook_missing_reference)

docs/index.md

@@ -3,11 +3,114 @@
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/UncountablePythonSDK)
 
 
-`Uncountable Python SDK` is a python package that allows interacting with the uncountable platform
+The Uncountable Python SDK is a python package that provides a wrapper around the Uncountable REST API.
 
-```{toctree}
-:maxdepth: 2
+Using this SDK provides the following advantages:
+
+- In-editor parameter/type safety
+- Automatic parsing of response data.
+- Reduced code boilerplate
+- Helper methods
+
+## Getting Started
+The first step in any integration is to create a [Client](uncountable.core.client.Client) object. The client provides access to all available SDK methods, and includes built-in request authentication & error propagation.
+
+### Creating a Client
+Create a client using one of the supported authentication mechanisms. API credentials can be generated by a member of Uncountable staff.
+
+::::{tab-set}
+:::{tab-item} Basic Auth
+```{literalinclude} ../examples/basic_auth.py
+```
+:::
+
+:::{tab-item} OAuth
+```{literalinclude} ../examples/oauth.py
+```
+:::
+::::
+
+The provided code examples assume that a Client has been created and stored in the `client` variable
+
+
+### Basic Usage
+
+:::{dropdown} List Ingredient Names & IDs
+```{code-block} python
+from uncountable.types import entity_t, id_source_t
+
+client.list_id_source(
+    spec=id_source_t.IdSourceSpecEntity(entity_type=entity_t.EntityType.INGREDIENT),
+    search_label="",
+)
+```
+Example Response:
+```code
+Data(
+    results=[
+        IdName(id=1, name='Filler'), 
+        IdName(id=2, name='Calcium Oxide 2'), 
+        IdName(id=3, name='Carbon Black'),
+    ]
+)
+```
+:::
+
+:::{dropdown} Create an Experiment
+```{code-block} python
+client.create_recipe(material_family_id=1, workflow_id=1, name="Example Recipe")
+```
+Example Response:
+```code
+Data(result_id=52271)
+```
+:::
+
+:::{dropdown} Upload a file
+```{code-block} python
+from uncountable.core.file_upload import MediaFileUpload
+
+client.upload_files(file_uploads=[MediaFileUpload(path="/path/to/local/example_file.pdf")])
+```
+Example Response:
+```code
+[
+    UploadedFile(name='example_file.pdf', file_id=718)
+]
+```
+:::
+
+[More examples](integration_examples/index)
+
+## Errors
+Client methods will raise Exceptions when the API returns codes in the `3xx`, `4xx` or `5xx` ranges. Ensure all method calls are wrapped in Exception handling logic.
+
+## Pagination
+Many of the Uncountable APIs require pagination to fetch more than 100 results at once. The following code snippet implements pagination to fetch the Names & IDs of all Projects:
+:::{dropdown} Pagination Example
+```{code-block} python
+from uncountable.types import entity_t, id_source_t
+from uncountable.types.api.id_source.list_id_source import IdName
 
-quickstart
+def fetch_all_projects(client: Client) -> list[IdName]:
+    projects: list[IdName] = []
+    while True:
+        response = client.list_id_source(
+            spec=IdSourceSpecEntity(entity_type=entity_t.EntityType.PROJECT),
+            search_label="",
+            offset=len(projects),
+        )
+        projects.extend(response.results)
+        if len(response.results) < 100:
+            return projects
 ```
+:::
 
+
+```{toctree}
+:hidden:
+Overview <self>
+Available SDK Methods <api/uncountable/core/client/Client>
+integration_examples/index
+SDK Reference <api/uncountable/index>
+```

docs/integration_examples/create_ingredient.md

@@ -0,0 +1,43 @@
+# Create an Ingredient
+
+Use the `create_or_update_entity` method to create Ingredients.
+
+The following fields are required when creating an Ingredient:
+- `name`: The name of the Ingredient
+- `core_ingredient_ingredientMaterialFamilies`: The list of material families in which to include the Ingredient
+
+The reference name of the default definition of Ingredients is `uncIngredient`
+
+This is an example of a minimal ingredient creation call
+
+```{code-block} python
+from uncountable.types import entity_t, field_values_t, identifier_t
+
+client.create_or_update_entity(
+    entity_type=entity_t.EntityType.INGREDIENT,
+    definition_key=identifier_t.IdentifierKeyRefName(ref_name="uncIngredient"),
+    field_values=[
+        field_values_t.FieldArgumentValue(
+            field_key=identifier_t.IdentifierKeyRefName(
+                ref_name="core_ingredient_ingredientMaterialFamilies"
+            ),
+            value=field_values_t.FieldValueIds(
+                entity_type=entity_t.EntityType.MATERIAL_FAMILY,
+                identifier_keys=[identifier_t.IdentifierKeyId(id=1)],
+            ),
+        ),
+        field_values_t.FieldArgumentValue(
+            field_key=identifier_t.IdentifierKeyRefName(ref_name="name"),
+            value=field_values_t.FieldValueText(value="Example Ingredient"),
+        ),
+    ],
+)
+```
+
+Example Response:
+```{code}
+Data(modification_made=True, result_id=3124, entity=None, result_values=None)
+```
+
+Optional fields:
+- `core_ingredient_quantityType`: The quantity type of the ingredient (default is `numeric`)

docs/integration_examples/create_output.md

@@ -0,0 +1,56 @@
+# Create an Output
+
+Use the `create_or_update_entity` method to create Outputs.
+
+The following fields are required when creating an Output:
+- `name`: The name of the Output
+- `core_output_unitsId`: The unit the output is measured in
+- `core_output_outputMaterialFamilies`: The list of material families in which to include the Output
+- `core_output_quantityType`: The quantity type of the output
+
+The reference name of the default definition of Ingredients is `unc_output_definition`
+
+This is an example of a minimal output creation call
+
+```{code-block} python
+from uncountable.types import entity_t, field_values_t, identifier_t
+
+client.create_or_update_entity(
+    entity_type=entity_t.EntityType.OUTPUT,
+    definition_key=identifier_t.IdentifierKeyRefName(ref_name="unc_output_definition"),
+    field_values=[
+        field_values_t.FieldArgumentValue(
+            field_key=identifier_t.IdentifierKeyRefName(ref_name="name"),
+            value=field_values_t.FieldValueText(value="Example Output"),
+        ),
+        field_values_t.FieldArgumentValue(
+            field_key=identifier_t.IdentifierKeyRefName(ref_name="core_output_unitsId"),
+            value=field_values_t.FieldValueId(
+                entity_type=entity_t.EntityType.UNITS,
+                identifier_key=identifier_t.IdentifierKeyId(id=1),
+            ),
+        ),
+        field_values_t.FieldArgumentValue(
+            field_key=identifier_t.IdentifierKeyRefName(
+                ref_name="core_output_outputMaterialFamilies"
+            ),
+            value=field_values_t.FieldValueIds(
+                entity_type=entity_t.EntityType.MATERIAL_FAMILY,
+                identifier_keys=[identifier_t.IdentifierKeyId(id=1)],
+            ),
+        ),
+        field_values_t.FieldArgumentValue(
+            field_key=identifier_t.IdentifierKeyRefName(
+                ref_name="core_output_quantityType"
+            ),
+            value=field_values_t.FieldValueFieldOption(value="numeric"),
+        ),
+    ],
+)
+```
+
+Example Response:
+
+```{code}
+Data(modification_made=True, result_id=653, entity=None, result_values=None)
+```

docs/integration_examples/index.md

@@ -0,0 +1,6 @@
+# Integration Examples
+
+```{toctree}
+create_ingredient
+create_output
+```

docs/justfile

@@ -1,5 +1,6 @@
 docs-setup-python:
-  pip install -r requirements.txt
+  curl -LsSf https://astral.sh/uv/0.8.4/install.sh | sh
+  uv pip install -r requirements.txt
 
 docs-clean:
   rm -rf _build/
@@ -9,4 +10,3 @@ docs-build: docs-clean
 
 docs-serve: docs-build
   npx serve _build/dirhtml
-

docs/requirements.txt

@@ -1,7 +1,9 @@
-furo==2024.8.6
-myst-parser==4.0.0
-sphinx-autoapi==3.3.0
+furo==2025.9.25
+myst-parser==4.0.1
+sphinx-autoapi==3.6.0
 sphinx-copybutton==0.5.2
-Sphinx==8.1.3
+Sphinx==8.2.0
 sphinx_design==0.6.1
 sphinx-favicon==1.0.1
+astroid==3.3.8
+docutils==0.21.2

examples/basic_auth.py

@@ -0,0 +1,7 @@
+from uncountable.core.client import Client
+from uncountable.core.types import AuthDetailsApiKey
+
+client = Client(
+    base_url="https://app.uncountable.com",
+    auth_details=AuthDetailsApiKey(api_id="x", api_secret_key="x"),
+)

examples/create_ingredient_sdk.py

@@ -0,0 +1,34 @@
+import os
+
+import uncountable.types.api.inputs.create_inputs as create_inputs
+from uncountable.core import AuthDetailsApiKey, Client
+from uncountable.types import field_values_t, inputs_t
+
+client = Client(
+    base_url="http://localhost:5000",
+    auth_details=AuthDetailsApiKey(
+        api_id=os.environ["UNC_API_ID"],
+        api_secret_key=os.environ["UNC_API_SECRET_KEY"],
+    ),
+)
+
+client.external_create_inputs(
+    inputs_to_create=[
+        create_inputs.InputToCreate(
+            name="sdk test ing",
+            material_family_ids=[1],
+            quantity_type=inputs_t.IngredientQuantityType.NUMERIC,
+            type=inputs_t.IngredientType.INGREDIENT,
+            field_values=[
+                field_values_t.FieldRefNameValue(
+                    field_ref_name="carrieTestNumericField",
+                    value="10",
+                ),
+                field_values_t.FieldRefNameValue(
+                    field_ref_name="carrieTestCheckboxField",
+                    value=True,
+                ),
+            ],
+        )
+    ]
+)

examples/download_files.py

@@ -0,0 +1,26 @@
+import os
+from pprint import pprint
+
+from uncountable.core import AuthDetailsApiKey, Client
+from uncountable.types import download_file_t, entity_t, identifier_t
+
+client = Client(
+    base_url="http://localhost:5000",
+    auth_details=AuthDetailsApiKey(
+        api_id=os.environ["UNC_API_ID"],
+        api_secret_key=os.environ["UNC_API_SECRET_KEY"],
+    ),
+)
+
+file_query = download_file_t.FileDownloadQueryEntityField(
+    entity=entity_t.EntityIdentifier(
+        type=entity_t.EntityType.LAB_REQUEST,
+        identifier_key=identifier_t.IdentifierKeyId(id=2375),
+    ),
+    field_key=identifier_t.IdentifierKeyRefName(ref_name="attachments"),
+)
+
+downloaded = client.download_files(
+    file_query=file_query,
+)
+pprint(downloaded)

examples/integration-server/jobs/materials_auto/concurrent_cron.py

@@ -0,0 +1,11 @@
+import time
+
+from uncountable.integration.job import CronJob, JobArguments, register_job
+from uncountable.types.job_definition_t import JobResult
+
+
+@register_job
+class MyConcurrentCronJob(CronJob):
+    def run(self, args: JobArguments) -> JobResult:
+        time.sleep(10)
+        return JobResult(success=True)

examples/integration-server/jobs/materials_auto/example_cron.py

@@ -1,3 +1,5 @@
+import time
+
 from uncountable.integration.job import CronJob, JobArguments, register_job
 from uncountable.types import entity_t
 from uncountable.types.job_definition_t import JobResult
@@ -15,4 +17,5 @@ class MyCronJob(CronJob):
             if field_val.field_ref_name == "name":
                 name = field_val.value
         args.logger.log_info(f"material family found with name: {name}")
+        time.sleep(1.5)
         return JobResult(success=True)

examples/integration-server/jobs/materials_auto/example_http.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+
+from uncountable.integration.http_server import (
+    GenericHttpRequest,
+    GenericHttpResponse,
+)
+from uncountable.integration.http_server.types import HttpException
+from uncountable.integration.job import CustomHttpJob, register_job
+from uncountable.types import job_definition_t
+
+
+@dataclass(kw_only=True)
+class ExampleWebhookPayload:
+    id: int
+    message: str
+
+
+_EXPECTED_USER_ID = 1
+
+
+@register_job
+class HttpExample(CustomHttpJob):
+    @staticmethod
+    def validate_request(
+        *,
+        request: GenericHttpRequest,  # noqa: ARG004
+        job_definition: job_definition_t.HttpJobDefinitionBase,  # noqa: ARG004
+        profile_meta: job_definition_t.ProfileMetadata,  # noqa: ARG004
+    ) -> None:
+        if (
+            CustomHttpJob.get_validated_oauth_request_user_id(
+                request=request, profile_metadata=profile_meta
+            )
+            != _EXPECTED_USER_ID
+        ):
+            raise HttpException(
+                message="unauthorized; invalid oauth token", error_code=401
+            )
+
+    @staticmethod
+    def handle_request(
+        *,
+        request: GenericHttpRequest,  # noqa: ARG004
+        job_definition: job_definition_t.HttpJobDefinitionBase,  # noqa: ARG004
+        profile_meta: job_definition_t.ProfileMetadata,  # noqa: ARG004
+    ) -> GenericHttpResponse:
+        return GenericHttpResponse(response="OK", status_code=200)

examples/integration-server/jobs/materials_auto/example_instrument.py

@@ -0,0 +1,100 @@
+import json
+import time
+from dataclasses import dataclass
+from decimal import Decimal
+
+from uncountable.integration.job import JobArguments, WebhookJob, register_job
+from uncountable.types import (
+    base_t,
+    identifier_t,
+    job_definition_t,
+    sockets_t,
+)
+from uncountable.types.integration_session_t import IntegrationSessionInstrument
+from websockets.sync.client import connect
+from websockets.typing import Data
+
+from pkgs.argument_parser.argument_parser import CachedParser
+from pkgs.serialization_util import serialize_for_api
+
+
+@dataclass(kw_only=True)
+class InstrumentPayload:
+    equipment_id: base_t.ObjectId
+
+
+@register_job
+class InstrumentExample(WebhookJob[InstrumentPayload]):
+    def run(
+        self, args: JobArguments, payload: InstrumentPayload
+    ) -> job_definition_t.JobResult:
+        parser: CachedParser[sockets_t.SocketResponse] = CachedParser(
+            sockets_t.SocketResponse  # type:ignore[arg-type]
+        )
+
+        def parse_message(message: Data) -> sockets_t.SocketEventData | None:
+            try:
+                return parser.parse_api(json.loads(message)).data
+            except ValueError:
+                return None
+
+        integration_session = IntegrationSessionInstrument(
+            equipment_key=identifier_t.IdentifierKeyId(id=payload.equipment_id)
+        )
+        registration_info = args.client.register_sockets_token(
+            socket_request=sockets_t.SocketRequestIntegrationSession(
+                integration_session=integration_session
+            )
+        ).response
+        token = registration_info.token
+        room_key = registration_info.room_key
+        args.logger.log_info(f"Token: {token}")
+
+        with connect(
+            "ws://host.docker.internal:8765",
+            additional_headers={
+                "Authorization": f"Bearer {token}",
+                "X-UNC-EXTERNAL": "true",
+            },
+        ) as ws:
+            ws.send(
+                json.dumps(
+                    serialize_for_api(
+                        sockets_t.JoinRoomWithTokenSocketClientMessage(token=token)
+                    )
+                )
+            )
+            for i in range(10):
+                args.logger.log_info("Sending reading...")
+                ws.send(
+                    json.dumps(
+                        serialize_for_api(
+                            sockets_t.SendInstrumentReadingClientMessage(
+                                value=Decimal(i * 100), room_key=room_key
+                            )
+                        )
+                    )
+                )
+                time.sleep(0.75)
+
+            while True:
+                message = parse_message(ws.recv())
+                match message:
+                    case sockets_t.UsersInRoomUpdatedEventData():
+                        num_users = len(message.user_ids)
+                        if num_users <= 1:
+                            break
+                        else:
+                            args.logger.log_info(
+                                f"Session still open, {num_users} users in room."
+                            )
+                    case _:
+                        args.logger.log_info("Session still open...")
+                        continue
+
+        args.logger.log_info("Session closed.")
+        return job_definition_t.JobResult(success=True)
+
+    @property
+    def webhook_payload_type(self) -> type:
+        return InstrumentPayload