UncountablePythonSDK 0.0.122__py3-none-any.whl → 0.0.124__py3-none-any.whl

docs/conf.py

@@ -27,7 +27,7 @@ extensions = [
     "sphinx_copybutton",
     "sphinx_favicon",
 ]
-myst_enable_extensions = ["fieldlist", "deflist"]
+myst_enable_extensions = ["fieldlist", "deflist", "colon_fence"]
 
 autoapi_dirs = ["../uncountable"]
 autoapi_options = [
@@ -70,14 +70,33 @@ def _hook_missing_reference(
     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
-    module, name = target.rsplit(".", 1)
+
+    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=name if python_use_unqualified_type_names else target,
+        text=target_name if python_use_unqualified_type_names else target,
         children=[contnode],
-        refuri=f"/{autoapi_root}/{module.replace('.', '/')}/#{target}",
+        refuri=full_relative_path,
     )
 
 

docs/index.md

@@ -3,14 +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.
+
+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
+
+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}
-:maxdepth: 2
 :hidden:
-
-quickstart
+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/requirements.txt

@@ -1,5 +1,5 @@
 furo==2025.7.19
-myst-parser==4.0.0
+myst-parser==4.0.1
 sphinx-autoapi==3.6.0
 sphinx-copybutton==0.5.2
 Sphinx==8.2.0

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/pyproject.toml

@@ -9,7 +9,7 @@ dependencies = [
   "ruff == 0.*",
   "openpyxl == 3.*",
   "more_itertools == 10.*",
-  "types-paramiko ==3.5.0.20250708",
+  "types-paramiko ==3.5.0.20250801",
   "types-openpyxl == 3.*",
   "types-pysftp == 0.*",
   "types-pytz ==2025.*",

examples/oauth.py

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

pkgs/argument_parser/_is_namedtuple.py

@@ -5,6 +5,9 @@ def is_namedtuple_type(x: Any) -> bool:
     if not hasattr(x, "__annotations__"):
         return False
 
+    if not hasattr(x, "__bases__"):
+        return False
+
     b = x.__bases__
     if len(b) != 1 or b[0] is not tuple:
         return False

pkgs/type_spec/type_info/emit_type_info.py

@@ -267,7 +267,9 @@ def _extract_and_validate_layout(
     for group in ext_info.layout.groups:
         fields = set(group.fields or [])
         for field in fields:
-            assert field in stype.properties, f"layout-refers-to-missing-field:{field}"
+            assert field in stype.properties or field == DISCRIMINATOR_COMMON_NAME, (
+                f"layout-refers-to-missing-field:{field}"
+            )
 
         local_ref_name = None
         if group.ref_name is not None:
@@ -314,6 +316,9 @@ def _pull_property_from_type_recursively(
     return _pull_property_from_type_recursively(stype.base, property_name)
 
 
+DISCRIMINATOR_COMMON_NAME = "type"
+
+
 def _validate_type_ext_info(
     stype: builder.SpecTypeDefnObject,
 ) -> tuple[ExtInfoLayout | None, type_info_t.ExtInfo | None]:
@@ -324,12 +329,16 @@ def _validate_type_ext_info(
     if ext_info.label_fields is not None:
         assert stype.properties is not None
         for name in ext_info.label_fields:
+            if name == DISCRIMINATOR_COMMON_NAME:
+                continue
             prop = _pull_property_from_type_recursively(stype, name)
             assert prop is not None, f"missing-label-field:{name}"
 
     if ext_info.actions is not None:
         assert stype.properties is not None
         for action in ext_info.actions:
+            if action.property == DISCRIMINATOR_COMMON_NAME:
+                continue
             prop = _pull_property_from_type_recursively(stype, action.property)
             assert prop is not None, f"missing-action-field:{action.property}"
 

uncountable/integration/http_server/types.py

@@ -1,5 +1,6 @@
 import base64
 import functools
+import json
 from dataclasses import dataclass
 
 from flask.wrappers import Response
@@ -42,7 +43,8 @@ class HttpException(Exception):
 
     def make_error_response(self) -> Response:
         return Response(
-            status=self.error_code, response={"error": {"message": str(self)}}
+            status=self.error_code,
+            response=json.dumps({"error": {"message": str(self)}}),
         )
 
 

uncountable/integration/scheduler.py

@@ -5,6 +5,7 @@ import sys
 import time
 from dataclasses import dataclass
 from datetime import UTC
+from enum import StrEnum
 
 from opentelemetry.trace import get_current_span
 
@@ -19,11 +20,19 @@ from uncountable.integration.telemetry import Logger
 
 SHUTDOWN_TIMEOUT_SECS = 30
 
+AnyProcess = multiprocessing.Process | subprocess.Popen[bytes]
+
+
+class ProcessName(StrEnum):
+    QUEUE_RUNNER = "queue_runner"
+    CRON_SERVER = "cron_server"
+    UWSGI = "uwsgi"
+
 
 @dataclass(kw_only=True)
 class ProcessInfo:
-    name: str
-    process: multiprocessing.Process | subprocess.Popen[bytes]
+    name: ProcessName
+    process: AnyProcess
 
     @property
     def is_alive(self) -> bool:
@@ -46,14 +55,14 @@ class ProcessInfo:
                 return self.process.poll()
 
 
-def handle_shutdown(logger: Logger, processes: list[ProcessInfo]) -> None:
+def handle_shutdown(logger: Logger, processes: dict[ProcessName, ProcessInfo]) -> None:
     logger.log_info("received shutdown command, shutting down sub-processes")
-    for proc_info in processes:
+    for proc_info in processes.values():
         if proc_info.is_alive:
             proc_info.process.terminate()
 
     shutdown_start = time.time()
-    still_living_processes = processes
+    still_living_processes = list(processes.values())
     while (
         time.time() - shutdown_start < SHUTDOWN_TIMEOUT_SECS
         and len(still_living_processes) > 0
@@ -82,14 +91,50 @@ def handle_shutdown(logger: Logger, processes: list[ProcessInfo]) -> None:
         proc_info.process.kill()
 
 
-def check_process_alive(logger: Logger, processes: list[ProcessInfo]) -> None:
-    for proc_info in processes:
+def restart_process(
+    logger: Logger, proc_info: ProcessInfo, processes: dict[ProcessName, ProcessInfo]
+) -> None:
+    logger.log_error(
+        f"process {proc_info.name} shut down unexpectedly - exit code {proc_info.exitcode}. Restarting..."
+    )
+
+    match proc_info.name:
+        case ProcessName.QUEUE_RUNNER:
+            queue_proc = multiprocessing.Process(target=start_queue_runner)
+            queue_proc.start()
+            new_info = ProcessInfo(name=ProcessName.QUEUE_RUNNER, process=queue_proc)
+            processes[ProcessName.QUEUE_RUNNER] = new_info
+            try:
+                _wait_queue_runner_online()
+                logger.log_info("queue runner restarted successfully")
+            except Exception as e:
+                logger.log_exception(e)
+                logger.log_error(
+                    "queue runner failed to restart, shutting down scheduler"
+                )
+                handle_shutdown(logger, processes)
+                sys.exit(1)
+
+        case ProcessName.CRON_SERVER:
+            cron_proc = multiprocessing.Process(target=cron_target)
+            cron_proc.start()
+            new_info = ProcessInfo(name=ProcessName.CRON_SERVER, process=cron_proc)
+            processes[ProcessName.CRON_SERVER] = new_info
+            logger.log_info("cron server restarted successfully")
+
+        case ProcessName.UWSGI:
+            uwsgi_proc: AnyProcess = subprocess.Popen(["uwsgi", "--die-on-term"])
+            new_info = ProcessInfo(name=ProcessName.UWSGI, process=uwsgi_proc)
+            processes[ProcessName.UWSGI] = new_info
+            logger.log_info("uwsgi restarted successfully")
+
+
+def check_process_alive(
+    logger: Logger, processes: dict[ProcessName, ProcessInfo]
+) -> None:
+    for proc_info in processes.values():
         if not proc_info.is_alive:
-            logger.log_error(
-                f"process {proc_info.name} shut down unexpectedly! shutting down scheduler; exit code is {proc_info.exitcode}"
-            )
-            handle_shutdown(logger, processes)
-            sys.exit(1)
+            restart_process(logger, proc_info, processes)
 
 
 def _wait_queue_runner_online() -> None:
@@ -113,17 +158,17 @@ def _wait_queue_runner_online() -> None:
 
 def main() -> None:
     logger = Logger(get_current_span())
-    processes: list[ProcessInfo] = []
+    processes: dict[ProcessName, ProcessInfo] = {}
 
     multiprocessing.set_start_method("forkserver")
 
     def add_process(process: ProcessInfo) -> None:
-        processes.append(process)
+        processes[process.name] = process
         logger.log_info(f"started process {process.name}")
 
     runner_process = multiprocessing.Process(target=start_queue_runner)
     runner_process.start()
-    add_process(ProcessInfo(name="queue runner", process=runner_process))
+    add_process(ProcessInfo(name=ProcessName.QUEUE_RUNNER, process=runner_process))
 
     try:
         _wait_queue_runner_online()
@@ -134,13 +179,13 @@ def main() -> None:
 
     cron_process = multiprocessing.Process(target=cron_target)
     cron_process.start()
-    add_process(ProcessInfo(name="cron server", process=cron_process))
+    add_process(ProcessInfo(name=ProcessName.CRON_SERVER, process=cron_process))
 
     uwsgi_process = subprocess.Popen([
         "uwsgi",
         "--die-on-term",
     ])
-    add_process(ProcessInfo(name="uwsgi", process=uwsgi_process))
+    add_process(ProcessInfo(name=ProcessName.UWSGI, process=uwsgi_process))
 
     try:
         while True:

uncountable/integration/telemetry.py

@@ -1,4 +1,5 @@
 import functools
+import json
 import os
 import time
 import traceback
@@ -32,6 +33,11 @@ def _cast_attributes(attributes: dict[str, base_t.JsonValue]) -> Attributes:
     return cast(Attributes, attributes)
 
 
+def one_line_formatter(record: LogRecord) -> str:
+    json_data = record.to_json()
+    return json.dumps(json.loads(json_data), separators=(",", ":")) + "\n"
+
+
 @functools.cache
 def get_otel_resource() -> Resource:
     attributes: dict[str, base_t.JsonValue] = {
@@ -60,7 +66,9 @@ def get_otel_tracer() -> Tracer:
 @functools.cache
 def get_otel_logger() -> OTELLogger:
     provider = LoggerProvider(resource=get_otel_resource())
-    provider.add_log_record_processor(BatchLogRecordProcessor(ConsoleLogExporter()))
+    provider.add_log_record_processor(
+        BatchLogRecordProcessor(ConsoleLogExporter(formatter=one_line_formatter))
+    )
     if get_otel_enabled():
         provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
     _logs.set_logger_provider(provider)

uncountable/types/__init__.py

@@ -50,6 +50,7 @@ from .api.inputs import get_input_names as get_input_names_t
 from .api.inputs import get_inputs_data as get_inputs_data_t
 from .api.outputs import get_output_data as get_output_data_t
 from .api.outputs import get_output_names as get_output_names_t
+from .api.outputs import get_output_organization as get_output_organization_t
 from .api.project import get_projects as get_projects_t
 from .api.project import get_projects_data as get_projects_data_t
 from .api.recipes import get_recipe_calculations as get_recipe_calculations_t
@@ -64,6 +65,7 @@ from . import identifier_t as identifier_t
 from . import input_attributes_t as input_attributes_t
 from . import inputs_t as inputs_t
 from . import integration_server_t as integration_server_t
+from . import integration_session_t as integration_session_t
 from . import integrations_t as integrations_t
 from .api.uploader import invoke_uploader as invoke_uploader_t
 from . import job_definition_t as job_definition_t
@@ -73,12 +75,14 @@ from .api.entity import lock_entity as lock_entity_t
 from .api.recipes import lock_recipes as lock_recipes_t
 from .api.entity import lookup_entity as lookup_entity_t
 from .api.id_source import match_id_source as match_id_source_t
+from . import notifications_t as notifications_t
 from . import outputs_t as outputs_t
 from . import overrides_t as overrides_t
 from . import permissions_t as permissions_t
 from . import phases_t as phases_t
 from . import post_base_t as post_base_t
 from .api.integrations import publish_realtime_data as publish_realtime_data_t
+from .api.integrations import push_notification as push_notification_t
 from . import queued_job_t as queued_job_t
 from . import recipe_identifiers_t as recipe_identifiers_t
 from . import recipe_inputs_t as recipe_inputs_t
@@ -108,6 +112,7 @@ from .api.recipes import set_recipe_output_file as set_recipe_output_file_t
 from .api.recipes import set_recipe_outputs as set_recipe_outputs_t
 from .api.recipes import set_recipe_tags as set_recipe_tags_t
 from .api.entity import set_values as set_values_t
+from . import sockets_t as sockets_t
 from .api.entity import transition_entity_phase as transition_entity_phase_t
 from .api.recipes import unarchive_recipes as unarchive_recipes_t
 from . import units_t as units_t
@@ -170,6 +175,7 @@ __all__: list[str] = [
     "get_inputs_data_t",
     "get_output_data_t",
     "get_output_names_t",
+    "get_output_organization_t",
     "get_projects_t",
     "get_projects_data_t",
     "get_recipe_calculations_t",
@@ -184,6 +190,7 @@ __all__: list[str] = [
     "input_attributes_t",
     "inputs_t",
     "integration_server_t",
+    "integration_session_t",
     "integrations_t",
     "invoke_uploader_t",
     "job_definition_t",
@@ -193,12 +200,14 @@ __all__: list[str] = [
     "lock_recipes_t",
     "lookup_entity_t",
     "match_id_source_t",
+    "notifications_t",
     "outputs_t",
     "overrides_t",
     "permissions_t",
     "phases_t",
     "post_base_t",
     "publish_realtime_data_t",
+    "push_notification_t",
     "queued_job_t",
     "recipe_identifiers_t",
     "recipe_inputs_t",
@@ -228,6 +237,7 @@ __all__: list[str] = [
     "set_recipe_outputs_t",
     "set_recipe_tags_t",
     "set_values_t",
+    "sockets_t",
     "transition_entity_phase_t",
     "unarchive_recipes_t",
     "units_t",

uncountable/types/api/entity/export_entities.py

@@ -18,12 +18,24 @@ __all__: list[str] = [
     "Data",
     "ENDPOINT_METHOD",
     "ENDPOINT_PATH",
+    "ListingAttribute",
 ]
 
 ENDPOINT_METHOD = "POST"
 ENDPOINT_PATH = "api/external/entity/export_entities"
 
 
+# DO NOT MODIFY -- This file is generated by type_spec
+@serial_class(
+    named_type_path="sdk.api.entity.export_entities.ListingAttribute",
+    unconverted_values={"value"},
+)
+@dataclasses.dataclass(slots=base_t.ENABLE_SLOTS, kw_only=True)  # type: ignore[literal-required]
+class ListingAttribute:
+    key: str
+    value: base_t.JsonValue
+
+
 # DO NOT MODIFY -- This file is generated by type_spec
 @serial_class(
     named_type_path="sdk.api.entity.export_entities.Arguments",
@@ -34,6 +46,7 @@ class Arguments:
     type: exports_t.ExportType = exports_t.ExportType.EXCEL
     client_timezone: exports_t.ListingExportUserTimezone | None = None
     limit: int | None = None
+    attributes: list[ListingAttribute] | None = None
 
 
 # DO NOT MODIFY -- This file is generated by type_spec