UncountablePythonSDK 0.0.115__py3-none-any.whl → 0.0.142.dev0__py3-none-any.whl

docs/conf.py

@@ -8,6 +8,11 @@
 
 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"{datetime.datetime.now(tz=datetime.UTC).date().year}, Uncountable Inc"
 author = "Uncountable Inc"
@@ -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,5 @@
 docs-setup-python:
-  curl -LsSf https://astral.sh/uv/0.7.1/install.sh | sh
+  curl -LsSf https://astral.sh/uv/0.8.4/install.sh | sh
   uv pip install -r requirements.txt
 
 docs-clean:

docs/requirements.txt

@@ -1,8 +1,9 @@
-furo==2024.8.6
-myst-parser==4.0.0
+furo==2025.9.25
+myst-parser==4.0.1
 sphinx-autoapi==3.6.0
 sphinx-copybutton==0.5.2
 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/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(20)
         return JobResult(success=True)

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

@@ -4,6 +4,7 @@ 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
 
@@ -14,22 +15,33 @@ class ExampleWebhookPayload:
     message: str
 
 
+_EXPECTED_USER_ID = 1
+
+
 @register_job
 class HttpExample(CustomHttpJob):
     @staticmethod
     def validate_request(
         *,
-        request: GenericHttpRequest,
-        job_definition: job_definition_t.HttpJobDefinitionBase,
-        profile_meta: job_definition_t.ProfileMetadata,
+        request: GenericHttpRequest,  # noqa: ARG004
+        job_definition: job_definition_t.HttpJobDefinitionBase,  # noqa: ARG004
+        profile_meta: job_definition_t.ProfileMetadata,  # noqa: ARG004
     ) -> None:
-        return 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,
-        job_definition: job_definition_t.HttpJobDefinitionBase,
-        profile_meta: job_definition_t.ProfileMetadata,
+        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

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

@@ -0,0 +1,140 @@
+from dataclasses import dataclass
+from decimal import Decimal
+
+from uncountable.integration.job import JobArguments, WebhookJob, register_job
+from uncountable.types import (
+    base_t,
+    entity_t,
+    generic_upload_t,
+    identifier_t,
+    job_definition_t,
+    notifications_t,
+    uploader_t,
+)
+
+
+@dataclass(kw_only=True)
+class ParsePayload:
+    async_job_id: base_t.ObjectId
+
+
+@register_job
+class ParseExample(WebhookJob[ParsePayload]):
+    def run(
+        self, args: JobArguments, payload: ParsePayload
+    ) -> job_definition_t.JobResult:
+        user_id: base_t.ObjectId | None = None
+        recipe_id: base_t.ObjectId | None = None
+        file_name: str | None = None
+        data = args.client.get_entities_data(
+            entity_ids=[payload.async_job_id], entity_type=entity_t.EntityType.ASYNC_JOB
+        )
+        for field_value in data.entity_details[0].field_values:
+            if field_value.field_ref_name == "core_async_job_jobData":
+                assert isinstance(field_value.value, dict)
+                assert isinstance(field_value.value["user_id"], int)
+                user_id = field_value.value["user_id"]
+            elif (
+                field_value.field_ref_name
+                == "unc_async_job_custom_parser_recipe_ids_in_view"
+            ):
+                if field_value.value is None:
+                    continue
+                assert isinstance(field_value.value, list)
+                if len(field_value.value) > 0:
+                    assert isinstance(field_value.value[0], int)
+                    recipe_id = field_value.value[0]
+            elif field_value.field_ref_name == "unc_async_job_custom_parser_input_file":
+                assert isinstance(field_value.value, list)
+                assert len(field_value.value) == 1
+                assert isinstance(field_value.value[0], dict)
+                assert isinstance(field_value.value[0]["name"], str)
+                file_name = field_value.value[0]["name"]
+
+        assert user_id is not None
+        assert file_name is not None
+
+        dummy_parsed_file_data: list[uploader_t.ParsedFileData] = [
+            uploader_t.ParsedFileData(
+                file_name=file_name,
+                file_structures=[
+                    uploader_t.DataChannel(
+                        type=uploader_t.StructureElementType.CHANNEL,
+                        channel=uploader_t.TextChannelData(
+                            name="column1",
+                            type=uploader_t.ChannelType.TEXT_CHANNEL,
+                            data=[
+                                uploader_t.StringValue(value="value1"),
+                                uploader_t.StringValue(value="value4"),
+                                uploader_t.StringValue(value="value7"),
+                            ],
+                        ),
+                    ),
+                    uploader_t.DataChannel(
+                        type=uploader_t.StructureElementType.CHANNEL,
+                        channel=uploader_t.TextChannelData(
+                            name="column2",
+                            type=uploader_t.ChannelType.TEXT_CHANNEL,
+                            data=[
+                                uploader_t.StringValue(value="value2"),
+                                uploader_t.StringValue(value="value5"),
+                                uploader_t.StringValue(value="value8"),
+                            ],
+                        ),
+                    ),
+                    uploader_t.DataChannel(
+                        type=uploader_t.StructureElementType.CHANNEL,
+                        channel=uploader_t.TextChannelData(
+                            name="column3",
+                            type=uploader_t.ChannelType.TEXT_CHANNEL,
+                            data=[
+                                uploader_t.StringValue(value="value3"),
+                                uploader_t.StringValue(value="value6"),
+                                uploader_t.StringValue(value="value9"),
+                            ],
+                        ),
+                    ),
+                    uploader_t.HeaderEntry(
+                        type=uploader_t.StructureElementType.HEADER,
+                        value=uploader_t.TextHeaderData(
+                            name="file_source",
+                            type=uploader_t.HeaderType.TEXT_HEADER,
+                            data=uploader_t.StringValue(value="my_file_to_upload.xlsx"),
+                        ),
+                    ),
+                    uploader_t.HeaderEntry(
+                        type=uploader_t.StructureElementType.HEADER,
+                        value=uploader_t.NumericHeaderData(
+                            name="file structure number",
+                            data=uploader_t.DecimalValue(value=Decimal(99)),
+                        ),
+                    ),
+                ],
+            )
+        ]
+
+        complete_async_parse_req = args.batch_processor.complete_async_parse(
+            parsed_file_data=dummy_parsed_file_data,
+            async_job_key=identifier_t.IdentifierKeyId(id=payload.async_job_id),
+            upload_destination=generic_upload_t.UploadDestinationRecipe(
+                recipe_key=identifier_t.IdentifierKeyId(id=recipe_id or 1)
+            ),
+        )
+
+        args.batch_processor.push_notification(
+            depends_on=[complete_async_parse_req.batch_reference],
+            notification_targets=[
+                notifications_t.NotificationTargetUser(
+                    user_key=identifier_t.IdentifierKeyId(id=user_id)
+                )
+            ],
+            subject="Upload complete",
+            message="Your file has been uploaded",
+            display_notice=True,
+        )
+
+        return job_definition_t.JobResult(success=True)
+
+    @property
+    def webhook_payload_type(self) -> type:
+        return ParsePayload