UncountablePythonSDK 0.0.24__py3-none-any.whl → 0.0.131__py3-none-any.whl

docs/conf.py

@@ -6,11 +6,15 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-from datetime import date
-import uncountable
+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 ---------------------------------------------------
@@ -23,16 +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', 'undoc-members', 'show-inheritance', 'show-module-summary', 'imported-members' ]
-autoapi_ignore = ['*integration*']
-autodoc_typehints = 'description'
+autoapi_options = [
+    "members",
+    "inherited-members",
+    "undoc-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
 
@@ -50,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.1.29
-myst-parser==2.0.0
-sphinx-autoapi==3.0.0
+furo==2025.9.25
+myst-parser==4.0.1
+sphinx-autoapi==3.6.0
 sphinx-copybutton==0.5.2
-Sphinx==7.2.6
-sphinx_design==0.5.0
+Sphinx==8.2.0
+sphinx_design==0.6.1
 sphinx-favicon==1.0.1
+astroid==3.3.8
+docutils==0.21.2

examples/async_batch.py

@@ -1,6 +1,7 @@
+import os
 from decimal import Decimal
-from uncountable.core import AuthDetailsApiKey, Client
-from uncountable.core import AsyncBatchProcessor
+
+from uncountable.core import AsyncBatchProcessor, AuthDetailsApiKey, Client
 from uncountable.types import (
     recipe_metadata,
 )
@@ -10,12 +11,10 @@ from uncountable.types.recipe_identifiers import (
     RecipeIdentifiers,
 )
 
-
 client = Client(
-    base_url="https://app.uncountable.com",
+    base_url=os.environ["UNC_BASE_URL"],
     auth_details=AuthDetailsApiKey(
-        api_id="X",
-        api_secret_key="X",
+        api_id=os.environ["UNC_API_ID"], api_secret_key=os.environ["UNC_API_SECRET_KEY"]
     ),
 )
 batch_loader = AsyncBatchProcessor(client=client)

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_entity.py

@@ -1,16 +1,14 @@
-from uncountable.core import AuthDetailsApiKey, Client
+from uncountable.core import AuthDetailsOAuth, Client
+from uncountable.core.client import ClientConfig
 from uncountable.types import (
     entity_t,
     field_values_t,
 )
 
-
 client = Client(
     base_url="https://app.uncountable.com",
-    auth_details=AuthDetailsApiKey(
-        api_id="X",
-        api_secret_key="X",
-    ),
+    auth_details=AuthDetailsOAuth(refresh_token="x"),
+    config=ClientConfig(allow_insecure_tls=False),
 )
 entities = client.create_entity(
     definition_id=24,

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/edit_recipe_inputs.py

@@ -0,0 +1,50 @@
+import os
+from decimal import Decimal
+
+from uncountable.core import AsyncBatchProcessor, AuthDetailsApiKey, Client
+from uncountable.types import (
+    edit_recipe_inputs_t,
+    recipe_workflow_steps_t,
+)
+from uncountable.types.identifier import IdentifierKeyBatchReference, IdentifierKeyId
+from uncountable.types.recipe_identifiers import (
+    RecipeIdentifiers,
+)
+from uncountable.types.recipe_inputs import QuantityBasis
+
+client = Client(
+    base_url=os.environ["UNC_BASE_URL"],
+    auth_details=AuthDetailsApiKey(
+        api_id=os.environ["UNC_API_ID"], api_secret_key=os.environ["UNC_API_SECRET_KEY"]
+    ),
+)
+batch_loader = AsyncBatchProcessor(client=client)
+recipe_identifiers: RecipeIdentifiers = []
+req = batch_loader.create_recipe(
+    material_family_id=1, workflow_id=1, identifiers=recipe_identifiers
+)
+created_recipe_reference = req.batch_reference
+edits: list[edit_recipe_inputs_t.RecipeInputEdit] = []
+edits.append(
+    edit_recipe_inputs_t.RecipeInputEditAddInput(
+        quantity_basis=QuantityBasis.MASS,
+        ingredient_key=IdentifierKeyId(id=1),
+        value_numeric=Decimal("56.7"),
+    )
+)
+edits.append(
+    edit_recipe_inputs_t.RecipeInputEditChangeBasisViewed(
+        quantity_basis=QuantityBasis.VOLUME, ingredient_key=IdentifierKeyId(id=1)
+    )
+)
+edits.append(
+    edit_recipe_inputs_t.RecipeInputEditAddInstructions(
+        instructions="Mix for 3 minutes"
+    )
+)
+batch_loader.edit_recipe_inputs(
+    recipe_key=IdentifierKeyBatchReference(reference=created_recipe_reference),
+    edits=edits,
+    recipe_workflow_step_identifier=recipe_workflow_steps_t.RecipeWorkflowStepIdentifierDefault(),
+)
+job_id = batch_loader.send()

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

@@ -0,0 +1,21 @@
+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
+
+
+@register_job
+class MyCronJob(CronJob):
+    def run(self, args: JobArguments) -> JobResult:
+        matfam = args.client.get_entities_data(
+            entity_ids=[1],
+            entity_type=entity_t.EntityType.MATERIAL_FAMILY,
+        ).entity_details[0]
+        name = None
+        for field_val in matfam.field_values:
+            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)