luminarycloud 0.10.0__tar.gz → 0.10.2__tar.gz

{luminarycloud-0.10.0/luminarycloud.egg-info → luminarycloud-0.10.2}/PKG-INFO

@@ -1,6 +1,7 @@
 Metadata-Version: 2.2
 Name: luminarycloud
-Version: 0.10.0
+Version: 0.10.2
+Summary: Luminary Cloud SDK
 Author: Luminary Cloud Inc.
 Author-email: support@luminarycloud.com
 Requires-Python: >=3.10

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/README.md

@@ -3,9 +3,9 @@
 - [Quickstart](#quickstart) **(recommended)**
 - [Manual Installation](#manual-installation)
 - [Building the wheel](#building-the-wheel)
-- [Generating Python proto files](#generating-python-proto-files)
 - [Generating documentation](#generating-documentation)
 - [Configuration](#configuration)
+- [Development Guide](#development-guide)
 
 ## Quickstart
 
@@ -24,14 +24,48 @@ the source has changed.
 - `docker compose run sdk pytest` to run unit tests.
 - `docker compose run sdk python my_script.py` to run an example script.
 
+## Running against a dev environment
+
+From within the `sdk` container, in a Python REPL, do the following to point the SDK to a dev
+environment:
+
+```
+>>> import luminarycloud as lc
+>>> from sdk_util import get_client_for_env
+>>> lc.set_default_client(get_client_for_env(env_name="{YOUR_ENV_NAME}"))
+```
+
+As with other environments, the first time you try to use your dev environment the SDK will will
+print a URL you need to follow to authenticate.
+
 ## SDK Releases
 
-Releases are managed manually via the [SDK Release GitHub Action](../../../.github/workflows/sdk-release.yaml).
+To release a new version of the SDK, create a PR with a commit that:
+ 1. bumps the `version` field in [`python/sdk/setup.cfg`](./setup.cfg),
+ 2. adds a new release notes file in `python/sdk/docs/source/releases/v{NEW_VERSION}.md`,
+ 3. adds the new version to the top of the `toctree` in [`python/sdk/docs/source/releases/index.md`](./docs/source/releases/index.md),
+
+Once that PR is merged, the rest happens automatically. First, the
+[SDK Auto Tag Release Commits workflow](../../../.github/workflows/sdk-auto-tag-release-commits.yaml)
+will tag the head of that PR branch with a release tag, `sdk-release/v{NEW_VERSION}`.
+
+Pushing the release tag triggers the [SDK Release workflow](../../../.github/workflows/sdk-release.yaml),
+which will send a message to slack asking for release approval. Once approved, the workflow will
+build the SDK wheel and upload it to PyPI. It will also build the docs and upload them to GCS.
 
-Create a new run of that workflow from either a branch or tag with prefix `sdk-release-*` and optionally:
+### Manual Release
+
+The [SDK Release workflow](../../../.github/workflows/sdk-release.yaml) also has a manual trigger.
+Environment protection rules are set up such that it can only be run against a branch or tag with
+prefix `sdk-release-*` or `sdk-release/*`.
+
+Running it manually gives you the following options:
 - check the `Publish to PyPI` box to publish the SDK to https://pypi.org/project/luminarycloud/
 - check the `Upload docs to GCS` box to upload the SDK docs; jobmaster will pick
   these up and serve them at app.luminarycloud.com/docs/api/ after it's next reboot
+- check the `Skip linting` box to skip the sanity checks that ensure the new release is documented
+  and the version is bumped correctly. You probably don't want to skip linting unless the linter is
+  making mistakes and you don't have time to fix it right this moment.
 
 Notes:
 - I've created an [sdk@luminarycloud.com
@@ -128,17 +162,6 @@ python -m build $CORE/python/sdk
 
 You will find the resulting wheel file in `$CORE/python/sdk/dist`.
 
-## Generating Python proto files
-
-This is only relevant for SDK developers. Run the following command to generate
-the *.py and *.pyi files from the proto files in `$CORE/proto`. Remember to `deactivate`
-any active virtualenvs before running this command (or you may end up with incorrect
-behavior).
-
-```sh
-$CORE/./bazel/gazelle.py
-```
-
 ## Generating documentation
 
 **[https://docs.eng.luminarycloud.com/python-sdk](https://docs.eng.luminarycloud.com/python-sdk)**
@@ -179,3 +202,7 @@ To see the values for other Auth0 tenants, see:
 
 You may set the above values inside a `.env` file placed at your project root or working directory.
 The values set in a `.env` do not override existing environment variables.
+
+## Development Guide
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for more information on how to develop the SDK.

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/luminarycloud/__init__.py

@@ -29,6 +29,7 @@ from .project import (
     create_project as create_project,
     get_project as get_project,
     list_projects as list_projects,
+    iterate_projects as iterate_projects,
     Project as Project,
 )
 from .simulation import (

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/luminarycloud/_helpers/__init__.py

@@ -8,6 +8,8 @@ from .create_simulation import (
 from .download import (
     download_surface_solution,
     download_volume_solution,
+    download_surface_deformation_template,
+    download_surface_sensitivity_data,
     save_file,
 )
 from .file_chunk_stream import (
@@ -20,6 +22,9 @@ from .simulation_params_from_json import (
 from .timestamp_to_datetime import (
     timestamp_to_datetime,
 )
+from .upload import (
+    upload_file,
+)
 from ._upload_mesh import (
     upload_mesh,
     upload_mesh_from_local_file,

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/luminarycloud/_helpers/_upload_table.py

@@ -57,13 +57,12 @@ def upload_table_as_json(
             project_id,
             uploadpb.ResourceParams(geometry_params=uploadpb.GeometryParams()),
             pathlib.Path(tmp_file_path),
-        ).url
+        )[1].url
 
 
 def upload_c81_as_json(
     client: Client,
     project_id: str,
-    name: str,
     c81: PathLike,
 ) -> str:
     """
@@ -75,8 +74,6 @@ def upload_c81_as_json(
         A LuminaryCloud Client (see client.py)
     project_id: str
         The ID of the project to upload the table under
-    name: str
-        Name to use for the uploaded file
     c81: PathLike
         Path to c81 file to upload
 
@@ -91,4 +88,4 @@ def upload_c81_as_json(
         project_id,
         uploadpb.ResourceParams(c81_params=uploadpb.C81Params()),
         pathlib.Path(c81),
-    ).url
+    )[1].url

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/luminarycloud/_helpers/create_geometry.py

@@ -34,7 +34,7 @@ def create_geometry(
         project_id,
         uploadpb.ResourceParams(geometry_params=uploadpb.GeometryParams()),
         cad_file_path,
-    )
+    )[1]
 
     # create geometry
     if name is None:

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/luminarycloud/_helpers/download.py

@@ -4,13 +4,15 @@ import logging
 import os
 from pathlib import Path
 import requests
-from typing import Iterator, Optional, Union, cast
+from typing import Any, Iterator, Optional, Union, cast
 
 from .file_chunk_stream import FileChunkStream
 from .._proto.api.v0.luminarycloud.common import common_pb2 as commonpb
 from .._proto.api.v0.luminarycloud.solution.solution_pb2 import (
     GetSolutionSurfaceDataRequest,
     GetSolutionVolumeDataRequest,
+    GetSurfaceDeformationTemplateRequest,
+    GetSurfaceSensitivityDataRequest,
 )
 from .._client import Client
 
@@ -59,6 +61,17 @@ def _iter_url(
         yield chunk
 
 
+def _create_file_chunk_stream(
+    client: Client, solution_id: str, data_desc: str, file: Any
+) -> FileChunkStream:
+    if file.signed_url:
+        logger.info(f"Begin streaming {data_desc} via signed URL for solution {solution_id}.")
+        return FileChunkStream(file.metadata, _iter_url(client, file.signed_url))
+
+    logger.info(f"Begin streaming {data_desc} via fetch URL for solution {solution_id}.")
+    return FileChunkStream(file.metadata, _iter_file_id(client, file.file_id))
+
+
 def download_surface_solution(
     client: Client,
     solution_id: str,
@@ -77,14 +90,7 @@ def download_surface_solution(
 
     request = GetSolutionSurfaceDataRequest(id=solution_id)
     response = client.GetSolutionSurfaceData(request)
-    file = response.file
-
-    if file.signed_url:
-        logger.info(f"Begin streaming surface data via signed URL for solution {solution_id}.")
-        return FileChunkStream(file.metadata, _iter_url(client, file.signed_url))
-
-    logger.info(f"Begin streaming surface data via fetch URL for solution {solution_id}.")
-    return FileChunkStream(file.metadata, _iter_file_id(client, file.file_id))
+    return _create_file_chunk_stream(client, solution_id, "surface solution", response.file)
 
 
 def download_volume_solution(
@@ -105,14 +111,34 @@ def download_volume_solution(
 
     request = GetSolutionVolumeDataRequest(id=solution_id)
     response = client.GetSolutionVolumeData(request)
-    file = response.file
+    return _create_file_chunk_stream(client, solution_id, "volume solution", response.file)
 
-    if file.signed_url:
-        logger.info(f"Begin streaming volume data via signed URL for solution {solution_id}.")
-        return FileChunkStream(file.metadata, _iter_url(client, file.signed_url))
 
-    logger.info(f"Begin streaming volume solution via fetch URL for solution {solution_id}.")
-    return FileChunkStream(file.metadata, _iter_file_id(client, file.file_id))
+def download_surface_deformation_template(
+    client: Client,
+    solution_id: str,
+) -> FileChunkStream:
+    """
+    Similar to download_surface_solution.
+    """
+    request = GetSurfaceDeformationTemplateRequest(id=solution_id)
+    response = client.GetSurfaceDeformationTemplate(request)
+    return _create_file_chunk_stream(
+        client, solution_id, "surface deformation template", response.file
+    )
+
+
+def download_surface_sensitivity_data(
+    client: Client,
+    solution_id: str,
+) -> FileChunkStream:
+    """
+    Similar to download_surface_solution.
+    """
+
+    request = GetSurfaceSensitivityDataRequest(id=solution_id)
+    response = client.GetSurfaceSensitivityData(request)
+    return _create_file_chunk_stream(client, solution_id, "surface sensitivity data", response.file)
 
 
 def save_file(

luminarycloud-0.10.2/luminarycloud/_helpers/proto_decorator.py

@@ -0,0 +1,47 @@
+# Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
+from typing import (
+    Generic,
+    TypeVar,
+    get_type_hints,
+    get_origin,
+)
+
+from google.protobuf.message import Message
+
+from luminarycloud.types import Vector3
+
+P = TypeVar("P", bound=Message)
+C = TypeVar("C")
+
+
+class proto_decorator(Generic[P]):
+    """
+    A decorator that adds a `to_proto` method to a class.
+
+    NOTE: only works for primitive and basepb.Vector3 fields right now.
+    """
+
+    def __init__(decorator, proto_type: type[P]):
+        decorator.proto_type = proto_type
+
+    def __call__(decorator, cls: type[C]) -> type[C]:
+        type_hints = get_type_hints(cls)
+        fields = decorator.proto_type.DESCRIPTOR.fields
+
+        def _to_proto(self) -> decorator.proto_type:
+            proto = decorator.proto_type()
+            for field in fields:
+                _type = type_hints.get(field.name, None)
+                if _type:
+                    value = getattr(self, field.name)
+                    if issubclass(_type, Vector3):
+                        vector_proto = getattr(proto, field.name)
+                        vector_proto.x = value.x
+                        vector_proto.y = value.y
+                        vector_proto.z = value.z
+                    else:
+                        setattr(proto, field.name, value)
+            return proto
+
+        setattr(cls, "_to_proto", _to_proto)
+        return cls

{luminarycloud-0.10.0 → luminarycloud-0.10.2}/luminarycloud/_helpers/upload.py

@@ -71,7 +71,7 @@ def upload_file(
     project_id: str,
     resource_params: uploadpb.ResourceParams,
     file_path: PathLike,
-) -> uploadpb.FinishUploadReply:
+) -> tuple[str, uploadpb.FinishUploadReply]:
     file_metadata = util.get_file_metadata(pathlib.Path(file_path))
 
     create_upload_res: uploadpb.CreateUploadReply = client.CreateUpload(
@@ -101,4 +101,4 @@ def upload_file(
     )
     logger.debug(f"finished upload")
 
-    return finish_res
+    return upload_id, finish_res

luminarycloud-0.10.2/luminarycloud/_helpers/warnings/__init__.py

@@ -0,0 +1,2 @@
+from .deprecated import deprecated
+from .experimental import experimental

luminarycloud-0.10.2/luminarycloud/_helpers/warnings/deprecated.py

@@ -0,0 +1,31 @@
+import warnings
+from functools import wraps
+from typing import Callable
+
+
+def deprecated(reason: str, version: str) -> Callable[[Callable], Callable]:
+    """
+    Mark a function as deprecated.
+
+    Parameters
+    ----------
+    reason : str
+        The reason for deprecation.
+    version : str
+        The version in which the function was deprecated.
+    """
+
+    def decorator(f: Callable) -> Callable:
+
+        @wraps(f)
+        def new_func(*args, **kwargs):
+            warnings.warn(
+                f"{f.__name__} is deprecated since version {version}: {reason}",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            return f(*args, **kwargs)
+
+        return new_func
+
+    return decorator

luminarycloud-0.10.2/luminarycloud/_helpers/warnings/experimental.py

@@ -0,0 +1,18 @@
+import warnings
+from functools import wraps
+from typing import Callable
+
+
+def experimental(f: Callable) -> Callable:
+    """Mark a function as experimental."""
+
+    @wraps(f)
+    def new_func(*args, **kwargs):
+        warnings.warn(
+            f"{f.__name__} is an experimental feature and may change or be removed without notice.",
+            category=FutureWarning,
+            stacklevel=2,
+        )
+        return f(*args, **kwargs)
+
+    return new_func