RSSeismicScripting 3.0.0__py3-none-any.whl

rsseismic/_proto_converters.py

@@ -0,0 +1,345 @@
+"""Convert protobuf messages to public types (internal)."""
+
+from __future__ import annotations
+
+from rsseismic.generatedFiles import MeanProfileService_pb2 as MeanProfileService_pb2
+from rsseismic.generatedFiles import MotionService_pb2 as MotionService_pb2
+from rsseismic.generatedFiles import ProfileService_pb2 as ProfileService_pb2
+from rsseismic.generatedFiles import ReferenceCurveDataService_pb2 as ReferenceCurveDataService_pb2
+from rsseismic.generatedFiles import ResultsService_pb2 as ResultsService_pb2
+from rsseismic.generatedFiles import SoilLayerCurveDataService_pb2 as SoilLayerCurveDataService_pb2
+from rsseismic.generatedFiles import SoilLayerService_pb2 as SoilLayerService_pb2
+from rsseismic.types import (
+    ActiveProfile,
+    AppendLayersResult,
+    BedrockLayerSummary,
+    DeconvolutionLayerResultFiles,
+    DeleteLayerResult,
+    DiscretePoint,
+    DynamicsPoint,
+    GqHFittingLimits,
+    InsertLayerResult,
+    MeanProfileAppendLayersResult,
+    MeanProfileDeleteLayerResult,
+    MeanProfileInsertLayerResult,
+    MeanProfileMoveLayerResult,
+    MeanProfileSummary,
+    MotionInfo,
+    MotionPairInfo,
+    MoveLayerResult,
+    ProfileSummary,
+    ResultDatabaseInfo,
+    ResultLayerSummary,
+    ResultMotionSummary,
+    SoilLayerSummary,
+)
+
+
+def from_mean_profile_response(
+    response: MeanProfileService_pb2.GetMeanProfileResponse,
+) -> MeanProfileSummary:
+    return MeanProfileSummary(
+        profileName=response.profileName,
+        layerCount=response.layerCount,
+        totalThickness=response.totalThickness,
+    )
+
+
+def from_mean_profile_soil_layer_entry(
+    entry: MeanProfileService_pb2.SoilLayerEntry,
+) -> SoilLayerSummary:
+    return SoilLayerSummary(
+        layerID=entry.layerID,
+        index1Based=entry.index1Based,
+        name=entry.name,
+        thickness=entry.thickness,
+    )
+
+
+def from_mean_profile_bedrock_layer_entry(
+    entry: MeanProfileService_pb2.BedrockLayerEntry,
+) -> BedrockLayerSummary:
+    return BedrockLayerSummary(
+        layerID=entry.layerID,
+        name=entry.name,
+        thickness=entry.thickness,
+    )
+
+
+def from_mean_profile_insert_layer_response(
+    response: MeanProfileService_pb2.InsertLayerResponse,
+) -> MeanProfileInsertLayerResult:
+    return MeanProfileInsertLayerResult(
+        layerID=response.layerID,
+        index1Based=response.index1Based,
+    )
+
+
+def from_mean_profile_append_layers_response(
+    response: MeanProfileService_pb2.AppendLayersResponse,
+) -> MeanProfileAppendLayersResult:
+    return MeanProfileAppendLayersResult(layerIDs=tuple(response.layerIDs))
+
+
+def from_mean_profile_delete_layer_response(
+    response: MeanProfileService_pb2.DeleteLayerResponse,
+) -> MeanProfileDeleteLayerResult:
+    return MeanProfileDeleteLayerResult(deletedLayerID=response.deletedLayerID)
+
+
+def from_mean_profile_move_layer_response(
+    response: MeanProfileService_pb2.MoveLayerResponse,
+) -> MeanProfileMoveLayerResult:
+    return MeanProfileMoveLayerResult(
+        layerID=response.layerID,
+        index1Based=response.index1Based,
+    )
+
+
+def from_profile_entry(entry: ProfileService_pb2.ProfileEntry) -> ProfileSummary:
+    return ProfileSummary(
+        name=entry.name,
+        isActive=entry.isActive,
+        layerCount=entry.layerCount,
+        totalThickness=entry.totalThickness,
+    )
+
+
+def from_active_profile_response(
+    response: ProfileService_pb2.GetActiveProfileResponse,
+) -> ActiveProfile:
+    return ActiveProfile(
+        profileName=response.profileName,
+        layerCount=response.layerCount,
+        totalThickness=response.totalThickness,
+    )
+
+
+def from_soil_layer_entry(entry: ProfileService_pb2.SoilLayerEntry) -> SoilLayerSummary:
+    return SoilLayerSummary(
+        layerID=entry.layerID,
+        index1Based=entry.index1Based,
+        name=entry.name,
+        thickness=entry.thickness,
+    )
+
+
+def from_bedrock_layer_entry(entry: ProfileService_pb2.BedrockLayerEntry) -> BedrockLayerSummary:
+    return BedrockLayerSummary(
+        layerID=entry.layerID,
+        name=entry.name,
+        thickness=entry.thickness,
+    )
+
+
+def from_motion_entry(entry: MotionService_pb2.MotionEntry) -> MotionInfo:
+    return MotionInfo(
+        name=entry.name,
+        filePath=entry.filePath,
+        isSelected=entry.isSelected,
+    )
+
+
+def from_motion_pair_entry(entry: MotionService_pb2.MotionPairEntry) -> MotionPairInfo:
+    return MotionPairInfo(
+        pairId=entry.pairId,
+        motionH1Name=entry.motionH1Name,
+        motionH2Name=entry.motionH2Name,
+        motionH1FilePath=entry.motionH1FilePath,
+        motionH2FilePath=entry.motionH2FilePath,
+        isSelected=entry.isSelected,
+    )
+
+
+def _motion_type_name(motion_type: int) -> str:
+    return ResultsService_pb2.MotionType.Name(motion_type)
+
+
+def from_deconvolution_layer_files(
+    entry: ResultsService_pb2.DeconvolutionLayerResultFiles,
+) -> DeconvolutionLayerResultFiles:
+    return DeconvolutionLayerResultFiles(
+        layerIndex=entry.layerIndex,
+        layerMotionPath=entry.layerMotionPath,
+        layerMotionExists=entry.layerMotionExists,
+        layerFasTransferFunctionPath=entry.layerFasTransferFunctionPath,
+        layerFasTransferFunctionExists=entry.layerFasTransferFunctionExists,
+    )
+
+
+def from_result_layer_entry(entry: ResultsService_pb2.ResultLayerEntry) -> ResultLayerSummary:
+    return ResultLayerSummary(
+        layerID=entry.layerID,
+        index1Based=entry.index1Based,
+        name=entry.name,
+        isTopOfRock=entry.isTopOfRock,
+    )
+
+
+def from_result_motion_entry(entry: ResultsService_pb2.ResultMotionEntry) -> ResultMotionSummary:
+    return ResultMotionSummary(
+        motionName=entry.motionName,
+        motionType=_motion_type_name(entry.motionType),
+        sourceMotionName=entry.sourceMotionName,
+    )
+
+
+def from_result_database_entry(entry: ResultsService_pb2.ResultDatabaseEntry) -> ResultDatabaseInfo:
+    return ResultDatabaseInfo(
+        profileName=entry.profileName,
+        motionName=entry.motionName,
+        motionType=_motion_type_name(entry.motionType),
+        resultsFolderPath=entry.resultsFolderPath,
+        resultDatabasePath=entry.resultDatabasePath,
+        resultDatabaseExists=entry.resultDatabaseExists,
+        complementaryResultDatabasePath=entry.complementaryResultDatabasePath,
+        complementaryResultDatabaseExists=entry.complementaryResultDatabaseExists,
+        inputFilePath=entry.inputFilePath,
+        inputFileExists=entry.inputFileExists,
+        strainConvergencePath=entry.strainConvergencePath,
+        strainConvergenceExists=entry.strainConvergenceExists,
+        strainNonConvergenceIdPath=entry.strainNonConvergenceIdPath,
+        strainNonConvergenceExists=entry.strainNonConvergenceExists,
+        deconvolutionBedrockMotionPath=entry.deconvolutionBedrockMotionPath,
+        deconvolutionBedrockMotionExists=entry.deconvolutionBedrockMotionExists,
+        deconvolutionBedrockFasTransferFunctionPath=entry.deconvolutionBedrockFasTransferFunctionPath,
+        deconvolutionBedrockFasTransferFunctionExists=entry.deconvolutionBedrockFasTransferFunctionExists,
+        deconvolutionLayerFiles=tuple(
+            from_deconvolution_layer_files(layer_file)
+            for layer_file in entry.deconvolutionLayerFiles
+        ),
+        topOfRockOutputEnabled=entry.topOfRockOutputEnabled,
+        topOfRockLayerID=entry.topOfRockLayerID,
+        topOfRockLayerIndex1Based=entry.topOfRockLayerIndex1Based,
+    )
+
+
+def from_insert_layer_response(response: SoilLayerService_pb2.InsertLayerResponse) -> InsertLayerResult:
+    return InsertLayerResult(
+        profileName=response.profileName,
+        layerID=response.layerID,
+        index1Based=response.index1Based,
+    )
+
+
+def from_append_layers_response(response: SoilLayerService_pb2.AppendLayersResponse) -> AppendLayersResult:
+    return AppendLayersResult(
+        profileName=response.profileName,
+        layerIDs=tuple(response.layerIDs),
+    )
+
+
+def from_delete_layer_response(response: SoilLayerService_pb2.DeleteLayerResponse) -> DeleteLayerResult:
+    return DeleteLayerResult(
+        profileName=response.profileName,
+        deletedLayerID=response.deletedLayerID,
+    )
+
+
+def from_move_layer_response(response: SoilLayerService_pb2.MoveLayerResponse) -> MoveLayerResult:
+    return MoveLayerResult(
+        profileName=response.profileName,
+        layerID=response.layerID,
+        index1Based=response.index1Based,
+    )
+
+
+def to_gq_h_fitting_limits_proto(
+    limits: GqHFittingLimits,
+) -> SoilLayerCurveDataService_pb2.GqHFittingLimits:
+    return SoilLayerCurveDataService_pb2.GqHFittingLimits(
+        enable_modulus_min=limits.enableModulusMin,
+        modulus_min=limits.modulusMin,
+        enable_modulus_max=limits.enableModulusMax,
+        modulus_max=limits.modulusMax,
+        enable_strength_min=limits.enableStrengthMin,
+        strength_min=limits.strengthMin,
+        enable_damp_min=limits.enableDampMin,
+        damp_min=limits.dampMin,
+        enable_damp_max=limits.enableDampMax,
+        damp_max=limits.dampMax,
+        enable_fix_theta3=limits.enableFixTheta3,
+        fix_theta3=limits.fixTheta3,
+    )
+
+
+def to_reference_curve_points(
+    points: list[DynamicsPoint],
+) -> list[ReferenceCurveDataService_pb2.ReferenceCurvePoint]:
+    return [
+        ReferenceCurveDataService_pb2.ReferenceCurvePoint(
+            strain=point.strain,
+            ggmax=point.ggmax,
+            damping=point.damping,
+            strength=point.strength,
+        )
+        for point in points
+    ]
+
+
+def from_reference_curve_points(
+    points: list[ReferenceCurveDataService_pb2.ReferenceCurvePoint],
+) -> list[DynamicsPoint]:
+    return [
+        DynamicsPoint(
+            strain=point.strain,
+            ggmax=point.ggmax,
+            damping=point.damping,
+            strength=point.strength,
+        )
+        for point in points
+    ]
+
+
+def to_dynamics_points(
+    points: list[DynamicsPoint],
+) -> list[SoilLayerCurveDataService_pb2.SoilLayerDynamicsPoint]:
+    return [
+        SoilLayerCurveDataService_pb2.SoilLayerDynamicsPoint(
+            strain=point.strain,
+            ggmax=point.ggmax,
+            damping=point.damping,
+            strength=point.strength,
+        )
+        for point in points
+    ]
+
+
+def from_dynamics_points(
+    points: list[SoilLayerCurveDataService_pb2.SoilLayerDynamicsPoint],
+) -> list[DynamicsPoint]:
+    return [
+        DynamicsPoint(
+            strain=point.strain,
+            ggmax=point.ggmax,
+            damping=point.damping,
+            strength=point.strength,
+        )
+        for point in points
+    ]
+
+
+def to_discrete_points(
+    points: list[DiscretePoint],
+) -> list[SoilLayerCurveDataService_pb2.DiscreteCurvePoint]:
+    return [
+        SoilLayerCurveDataService_pb2.DiscreteCurvePoint(
+            strain=point.strain,
+            ggmax=point.ggmax,
+            damping=point.damping,
+        )
+        for point in points
+    ]
+
+
+def from_discrete_points(
+    points: list[SoilLayerCurveDataService_pb2.DiscreteCurvePoint],
+) -> list[DiscretePoint]:
+    return [
+        DiscretePoint(
+            strain=point.strain,
+            ggmax=point.ggmax,
+            damping=point.damping,
+        )
+        for point in points
+    ]

rsseismic/_proxyObject.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from rsseismic._client import Client
+
+
+class _ProxyObject:
+    """Base type for handles to objects owned by RSSeismic."""
+
+    def __init__(self, client: Client, objectId: str):
+        self._client = client
+        self._objectId = objectId

rsseismic/_result_bulk_dataframes.py

@@ -0,0 +1,202 @@
+"""Helpers for bulk result DataFrame queries (compose single-motion RPCs)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+
+import pandas as pd
+
+from rsseismic.exceptions import ScriptingError
+from rsseismic.generatedFiles import ResultsService_pb2 as ResultsService_pb2
+from rsseismic.types import ResultDatabaseInfo, ResultMotionSummary, ResultMotionType
+
+
+def infer_el_convergence_motion_type_filter(
+    solution_type: str,
+    analysis_mode: str,
+    equivalent_linear: bool,
+) -> frozenset[ResultMotionType] | None:
+    """Mirror ResultsViewVM.GetELMotions motion-type rules for the convergence tab."""
+    if solution_type == "FrequencyDomain" and analysis_mode == "EquivalentLinear":
+        return None
+
+    if solution_type == "TimeDomain" and analysis_mode == "Nonlinear" and equivalent_linear:
+        return frozenset({ResultMotionType.COMPLEMENTARY_EQUIVALENT_LINEAR})
+
+    return frozenset()
+
+
+def select_motion_names_from_result_motions(
+    motions: Iterable[ResultMotionSummary],
+    motion_type_filters: frozenset[ResultMotionType] | None,
+) -> list[str]:
+    """Distinct motion names from listResultMotions(), optionally filtered by type."""
+    if motion_type_filters is not None and len(motion_type_filters) == 0:
+        return []
+
+    motion_names: list[str] = []
+    seen: set[str] = set()
+
+    for motion in motions:
+        if not motion_type_matches_filters(motion.motionType, motion_type_filters):
+            continue
+        if motion.motionName in seen:
+            continue
+        seen.add(motion.motionName)
+        motion_names.append(motion.motionName)
+
+    return motion_names
+
+
+def select_convergence_tab_motion_names(
+    motions: Iterable[ResultMotionSummary],
+    motion_type_filters: frozenset[ResultMotionType] | None,
+) -> list[str]:
+    """Motions shown on the Check convergence tab (GetELMotions)."""
+    return select_motion_names_from_result_motions(motions, motion_type_filters)
+
+
+def select_displacement_animation_motion_names(
+    motions: Iterable[ResultMotionSummary],
+) -> list[str]:
+    """All compute-aligned result motions (displacement animation tab motion list)."""
+    return select_motion_names_from_result_motions(motions, motion_type_filters=None)
+
+
+def normalize_result_motion_type_filters(
+    motion_type_filters: Sequence[ResultMotionType] | None,
+) -> frozenset[ResultMotionType] | None:
+    """Return None when filters are empty (meaning all motion types)."""
+    if motion_type_filters is None:
+        return None
+
+    filters = tuple(motion_type_filters)
+    if len(filters) == 0:
+        return None
+
+    for item in filters:
+        if not isinstance(item, ResultMotionType):
+            raise TypeError(
+                f"motionTypeFilters must contain ResultMotionType values; got {type(item)!r}."
+            )
+
+    return frozenset(filters)
+
+
+def result_motion_type_to_proto_name(motion_type: ResultMotionType) -> str:
+    if motion_type is ResultMotionType.COMPLEMENTARY_NONLINEAR_TOTAL_STRESS_LUMPED_MASS:
+        return ResultsService_pb2.MotionType.Name(
+            ResultsService_pb2.MOTION_TYPE_COMPLEMENTARY_NONLINEAR_TOTAL_STRESS
+        )
+    return ResultsService_pb2.MotionType.Name(int(motion_type))
+
+
+def _result_motion_type_from_proto_name(proto_name: str) -> ResultMotionType:
+    if proto_name == "MOTION_TYPE_COMPLEMENTARY_NONLINEAR_TOTAL_STRESS":
+        return ResultMotionType.COMPLEMENTARY_NONLINEAR_TOTAL_STRESS_LUMPED_MASS
+
+    try:
+        proto_value = ResultsService_pb2.MotionType.Value(proto_name)
+    except ValueError as exc:
+        raise ValueError(f"Unknown result motion type: {proto_name!r}") from exc
+
+    return ResultMotionType(proto_value)
+
+
+def motion_type_matches_filters(
+    motion_type_name: str,
+    motion_type_filters: frozenset[ResultMotionType] | None,
+) -> bool:
+    if motion_type_filters is None:
+        return True
+
+    motion_type = _result_motion_type_from_proto_name(motion_type_name)
+    return motion_type in motion_type_filters
+
+
+def select_profile_motion_names(
+    databases: Iterable[ResultDatabaseInfo],
+    profile_name: str,
+    motion_type_filters: frozenset[ResultMotionType] | None,
+    *,
+    require_strain_convergence: bool = False,
+    require_result_database: bool = False,
+) -> list[str]:
+    """Return distinct motion names for a profile from listResultDatabases entries."""
+    motion_names: list[str] = []
+    seen: set[str] = set()
+
+    for entry in databases:
+        if entry.profileName != profile_name:
+            continue
+        if require_strain_convergence and not entry.strainConvergenceExists:
+            continue
+        if require_result_database and not entry.resultDatabaseExists:
+            continue
+        if not motion_type_matches_filters(entry.motionType, motion_type_filters):
+            continue
+        if entry.motionName in seen:
+            continue
+
+        seen.add(entry.motionName)
+        motion_names.append(entry.motionName)
+
+    return motion_names
+
+
+def resolve_layer_ids(
+    layer_ids: Sequence[str] | None,
+    list_layers: Callable[[], Sequence[object]],
+) -> list[str]:
+    if layer_ids is None or len(layer_ids) == 0:
+        return [layer.layerID for layer in list_layers()]
+
+    return list(layer_ids)
+
+
+def fetch_bulk_dataframes(
+    motion_names: Sequence[str],
+    fetch_one: Callable[[str], pd.DataFrame],
+    *,
+    skip_errors: bool,
+) -> dict[str, pd.DataFrame]:
+    results: dict[str, pd.DataFrame] = {}
+
+    for motion_name in motion_names:
+        try:
+            results[motion_name] = fetch_one(motion_name)
+        except ScriptingError:
+            if not skip_errors:
+                raise
+
+    return results
+
+
+def fetch_bulk_layer_series_dataframes(
+    motion_names: Sequence[str],
+    layer_ids: Sequence[str],
+    fetch_one: Callable[[str, str], pd.DataFrame],
+    *,
+    skip_errors: bool,
+) -> dict[tuple[str, str], pd.DataFrame]:
+    results: dict[tuple[str, str], pd.DataFrame] = {}
+
+    for motion_name in motion_names:
+        for layer_id in layer_ids:
+            key = (motion_name, layer_id)
+            try:
+                results[key] = fetch_one(motion_name, layer_id)
+            except ScriptingError:
+                if not skip_errors:
+                    raise
+
+    return results
+
+
+def fetch_bulk_profile_series_dataframes(
+    motion_names: Sequence[str],
+    fetch_one: Callable[[str], pd.DataFrame],
+    *,
+    skip_errors: bool,
+) -> dict[str, pd.DataFrame]:
+    return fetch_bulk_dataframes(motion_names, fetch_one, skip_errors=skip_errors)

rsseismic/_result_dataframes.py

@@ -0,0 +1,77 @@
+"""Convert ResultsService DataTable messages to pandas DataFrames (internal)."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from rsseismic.generatedFiles import ResultsService_pb2 as ResultsService_pb2
+from rsseismic.types import ResultSeriesKind
+
+
+def data_table_to_dataframe(table: ResultsService_pb2.DataTable) -> pd.DataFrame:
+    """Build a DataFrame from a ResultsService DataTable proto message."""
+    column_count = len(table.columns)
+    data_count = len(table.data)
+    if column_count != data_count:
+        raise ValueError(
+            f"DataTable column count ({column_count}) does not match "
+            f"data column count ({data_count})."
+        )
+
+    frame_data = {
+        column_name: list(column.values)
+        for column_name, column in zip(table.columns, table.data)
+    }
+    dataframe = pd.DataFrame(frame_data)
+
+    if table.rowCount and len(dataframe) != table.rowCount:
+        raise ValueError(
+            f"DataTable rowCount ({table.rowCount}) does not match "
+            f"built DataFrame length ({len(dataframe)})."
+        )
+
+    if table.columnUnits:
+        dataframe.attrs["column_units"] = dict(zip(table.columns, table.columnUnits))
+
+    return dataframe
+
+
+def resolve_result_series_kind(kind: ResultSeriesKind | int | str) -> int:
+    """Resolve a public ResultSeriesKind (or legacy int/str) to a proto enum value."""
+    if isinstance(kind, ResultSeriesKind):
+        return int(kind)
+
+    if isinstance(kind, int):
+        try:
+            return int(ResultSeriesKind(kind))
+        except ValueError as exc:
+            raise ValueError(f"Unknown result series kind value: {kind}") from exc
+
+    if isinstance(kind, str):
+        name = kind.strip()
+        if not name:
+            raise ValueError("Result series kind is required.")
+
+        if name.startswith("RESULT_SERIES_"):
+            member_name = name.removeprefix("RESULT_SERIES_")
+            try:
+                return int(ResultSeriesKind[member_name])
+            except KeyError:
+                pass
+
+        normalized = name.upper().replace("-", "_")
+        try:
+            return int(ResultSeriesKind[normalized])
+        except KeyError:
+            pass
+
+        upper_name = normalized
+        if not upper_name.startswith("RESULT_SERIES_"):
+            upper_name = f"RESULT_SERIES_{upper_name}"
+
+        if upper_name in ResultsService_pb2.ResultSeriesKind.keys():
+            return ResultsService_pb2.ResultSeriesKind.Value(upper_name)
+
+        raise ValueError(f"Unknown result series kind: {kind!r}")
+
+    raise TypeError(f"Unsupported result series kind type: {type(kind)!r}")

rsseismic/_rpc_helpers.py

@@ -0,0 +1,55 @@
+"""Shared helpers for RSSeismic gRPC wrappers."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from rsseismic.exceptions import ScriptingError
+from rsseismic.generatedFiles import CommonMessages_pb2 as CommonMessages_pb2
+
+
+def require_success(response: Any, operation: str) -> None:
+    """Raise ScriptingError when a response message has success=false."""
+    if getattr(response, "success", False):
+        return
+    message = getattr(response, "errorMessage", "") or f"{operation} failed."
+    raise ScriptingError(message)
+
+
+def log_success_advisory(response: Any) -> None:
+    """When success is true, log a non-empty errorMessage as a warning (server advisory)."""
+    if not getattr(response, "success", False):
+        return
+    advisory_message = getattr(response, "errorMessage", "") or ""
+    if advisory_message:
+        from rsseismic import logger
+
+        logger.warning(advisory_message)
+
+
+def property_value_from_python(value: Any) -> CommonMessages_pb2.PropertyValue:
+    """Build a CommonMessages PropertyValue from a Python scalar."""
+    if isinstance(value, CommonMessages_pb2.PropertyValue):
+        return value
+    if isinstance(value, bool):
+        return CommonMessages_pb2.PropertyValue(boolValue=value)
+    if isinstance(value, int):
+        return CommonMessages_pb2.PropertyValue(longValue=value)
+    if isinstance(value, float):
+        return CommonMessages_pb2.PropertyValue(doubleValue=value)
+    if isinstance(value, bytes):
+        return CommonMessages_pb2.PropertyValue(bytesValue=value)
+    if isinstance(value, Enum):
+        return CommonMessages_pb2.PropertyValue(enumValue=value.value)
+    if isinstance(value, str):
+        return CommonMessages_pb2.PropertyValue(stringValue=value)
+    raise TypeError(f"Unsupported property value type: {type(value)!r}")
+
+
+def property_value_to_python(value: CommonMessages_pb2.PropertyValue) -> Any:
+    """Extract the Python scalar stored in a PropertyValue oneof."""
+    field = value.WhichOneof("value")
+    if field is None:
+        return None
+    return getattr(value, field)