Skip to content
7 changes: 7 additions & 0 deletions examples/spec/get_and_query_specs.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
ConditionType,
CreateSpecificationsRequest,
CreateSpecificationsRequestObject,
MeasurementMappingItem,
NumericConditionValue,
QuerySpecificationsRequest,
SpecificationLimit,
Expand Down Expand Up @@ -44,6 +45,12 @@
name="input voltage",
limit=SpecificationLimit(min=0.02, max=0.15),
unit="mV",
measurement_mapping=[
MeasurementMappingItem(
filter='data.parameters.Any(it["name"] == "Input Voltage")',
result_filter='partNumber == "VR1234"',
)
],
conditions=[
Condition(
name="Temperature",
Expand Down
50 changes: 37 additions & 13 deletions examples/spec/update_and_delete_specs.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
from nisystemlink.clients.core import HttpConfiguration
from nisystemlink.clients.spec import SpecClient
from nisystemlink.clients.spec.models import (
MeasurementMappingItem,
QuerySpecificationsRequest,
SpecificationType,
UpdateSpecificationsRequest,
Expand All @@ -24,18 +25,22 @@
# The query and delete examples assume you have created the specs from the query_specs example
product = "Amplifier"

# update spec1 to change the block to "modifiedBlock"
# query the original spec
# update spec1 to change the block to "modifiedBlock" and spec2 to set a measurement mapping,
# both in a single request
# query the original specs
spec_filter = 'specId == "spec1" || specId == "spec2"'
response = client.query_specs(
QuerySpecificationsRequest(product_ids=[product], filter='specId == "spec1"')
QuerySpecificationsRequest(product_ids=[product], filter=spec_filter)
)
if response.specs:
original_spec1 = response.specs[0]
original_specs = {spec.spec_id: spec for spec in response.specs or []}
if "spec1" in original_specs and "spec2" in original_specs:
original_spec1 = original_specs["spec1"]
original_spec2 = original_specs["spec2"]
print(f"Original spec1 block: {original_spec1.block}")
print(f"Original spec1 version: {original_spec1.version}")

# make the modifications
modified_spec = UpdateSpecificationsRequestObject(
modified_spec1 = UpdateSpecificationsRequestObject(
id=cast(str, original_spec1.id),
product_id=cast(str, original_spec1.product_id),
spec_id=cast(str, original_spec1.spec_id),
Expand All @@ -45,19 +50,38 @@
version=cast(int, original_spec1.version),
workspace=cast(str, original_spec1.workspace),
)
modified_spec2 = UpdateSpecificationsRequestObject(
id=cast(str, original_spec2.id),
product_id=cast(str, original_spec2.product_id),
spec_id=cast(str, original_spec2.spec_id),
type=SpecificationType.PARAMETRIC,
measurement_mapping=[
MeasurementMappingItem(
filter='data.parameters.Any(it["name"] == "Input Voltage")',
result_filter='partNumber == "VR5678"',
)
],
version=cast(int, original_spec2.version),
workspace=cast(str, original_spec2.workspace),
)
update_response = client.update_specs(
specs=UpdateSpecificationsRequest(specs=[modified_spec])
specs=UpdateSpecificationsRequest(specs=[modified_spec1, modified_spec2])
)
if update_response and update_response.updated_specs:
print(f"New spec1 version: {update_response.updated_specs[0].version}")
for updated_spec in update_response.updated_specs:
print(f"New {updated_spec.spec_id} version: {updated_spec.version}")

# query again to see new version
# query again to see the new versions
response = client.query_specs(
QuerySpecificationsRequest(product_ids=[product], filter='specId == "spec1"')
QuerySpecificationsRequest(product_ids=[product], filter=spec_filter)
)
if response.specs:
original_spec1 = response.specs[0]
print(f"Modified spec1 block: {original_spec1.block}")
modified_specs = {spec.spec_id: spec for spec in response.specs or []}
if "spec1" in modified_specs and "spec2" in modified_specs:
print(f"Modified spec1 block: {modified_specs['spec1'].block}")
print(
"Modified spec2 measurement mapping: "
f"{modified_specs['spec2'].measurement_mapping}"
)

# delete all the specs for the product
# query all specs
Expand Down
2 changes: 2 additions & 0 deletions nisystemlink/clients/spec/models/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
SpecificationProjection,
)
from ._specification import (
MeasurementMappingItem,
Specification,
SpecificationDefinition,
SpecificationLimit,
Expand Down Expand Up @@ -49,6 +50,7 @@
"PagedSpecifications",
"SpecificationOrderBy",
"SpecificationProjection",
"MeasurementMappingItem",
"Specification",
"SpecificationDefinition",
"SpecificationLimit",
Expand Down
3 changes: 3 additions & 0 deletions nisystemlink/clients/spec/models/_query_specs.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ class SpecificationProjection(str, Enum):
CREATED_AT = "CREATED_AT"
CREATED_BY = "CREATED_BY"
UPDATED_AT = "UPDATED_AT"
MEASUREMENT_MAPPING = "MEASUREMENT_MAPPING"


class SpecificationOrderBy(Enum):
Expand Down Expand Up @@ -82,6 +83,8 @@ class QuerySpecificationsRequest(JsonModel):
- `createdAt`: ISO-8601 formatted UTC timestamp indicating when the specification was created.
- `updatedBy`: String representing the ID of the user who updated the specification.
- `updatedAt`: ISO-8601 formatted UTC timestamp indicating when the specification was updated.
- `measurementMapping`: Query filters used to associate the specification with its measurement
data.

See [Dynamic Linq](https://github.com/ni/systemlink-OpenAPI-documents/wiki/Dynamic-Linq-Query-Language)
documentation for more details.
Expand Down
21 changes: 21 additions & 0 deletions nisystemlink/clients/spec/models/_specification.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,24 @@ class SpecificationType(Enum):
"""Functional specs only have pass/fail status."""


class MeasurementMappingItem(JsonModel):
"""Filters that map a specification to its measurement data."""

filter: str | None = None
Comment thread
Ahalya-ni marked this conversation as resolved.
Resolved
"""Query string specifying the filter criteria for selecting test steps mapped to the
specification.

Uses the Dynamic LINQ format of the Test Monitor query-steps API filter.
"""

result_filter: str | None = None
"""Query string specifying the filter criteria for selecting test results containing steps
mapped to the specification.

Uses the Dynamic LINQ format of the Test Monitor query-steps API resultFilter.
"""


class SpecificationDefinition(JsonModel):

product_id: str | None = None
Expand Down Expand Up @@ -84,6 +102,9 @@ class SpecificationDefinition(JsonModel):
properties: Dict[str, str] | None = None
"""Additional properties associated with the specification."""

measurement_mapping: List[MeasurementMappingItem] | None = None
"""Query filters used to associate the specification with its measurement data."""

workspace: str | None = None
"""Id of the workspace to which the specification will be associated.

Expand Down
3 changes: 3 additions & 0 deletions nisystemlink/clients/spec/utilities/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
summarize_conditions_as_a_string,
normalize_conditions_per_column,
normalize_conditions_per_row,
summarize_measurement_mappings_as_a_string,
normalize_measurement_mappings_per_column,
normalize_measurement_mappings_per_row,
)

# flake8: noqa
141 changes: 137 additions & 4 deletions nisystemlink/clients/spec/utilities/_dataframe_utilities.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
StringConditionValue,
)
from nisystemlink.clients.spec.models._specification import (
MeasurementMappingItem,
Specification,
SpecificationLimit,
SpecificationType,
Expand Down Expand Up @@ -92,11 +93,89 @@ def normalize_conditions_per_row(
]


def summarize_measurement_mappings_as_a_string(
measurement_mappings: List[MeasurementMappingItem],
) -> List[Dict[str, str]]:
"""Converts the measurement mappings to an easily readable string format.

Args:
measurement_mappings: List of all measurement mappings in a spec.

Returns:
A list with a single dictionary. The key will be "measurement_mapping" and the value
will be "[filter: <value>; result_filter: <value>], [filter: <value>]" where each
bracketed group is a mapping item. Fields that are None are left out and items
without any field are skipped. The list is empty if there is nothing to summarize.
"""
summaries = []
for item in measurement_mappings:
fields = __serialize_measurement_mapping_fields(item)
if fields:
summaries.append(
"["
+ "; ".join(f"{key}: {value}" for key, value in fields.items())
+ "]"
)

return [{"measurement_mapping": ", ".join(summaries)}] if summaries else []


def normalize_measurement_mappings_per_column(
measurement_mappings: List[MeasurementMappingItem],
) -> List[Dict[str, Any]]:
"""Convert measurement mappings into a single dictionary where each mapping item is
split into indexed keys.

Args:
measurement_mappings: List of all measurement mappings in a spec.

Returns:
A list with a single dictionary. The keys will be
"measurement_mapping[<index>].filter" and "measurement_mapping[<index>].result_filter"
and the values will be the corresponding mapping item field. Fields that are None
are left out. The list is empty if no mapping item has a value.
"""
columns = {
f"measurement_mapping[{index}].{key}": value
for index, item in enumerate(measurement_mappings)
for key, value in __serialize_measurement_mapping_fields(item).items()
}

return [columns] if columns else []


def normalize_measurement_mappings_per_row(
measurement_mappings: List[MeasurementMappingItem],
) -> List[Dict[str, Any]]:
"""Convert measurement mappings into list of dictionaries where dictionary keys will be
'measurement_mapping.filter' and 'measurement_mapping.result_filter'.

Args:
measurement_mappings: List of all measurement mappings in a spec.

Returns:
A list of dictionaries, one for each mapping item that has a value. Fields that
are None are left out. Each mapping item will be logged as separate dictionary
entry in the list which translates to separate row in the dataframe.
"""
return [
{f"measurement_mapping.{key}": value for key, value in fields.items()}
for fields in (
__serialize_measurement_mapping_fields(item)
for item in measurement_mappings
)
if fields
]


def convert_specs_to_dataframe(
specs: List[Specification],
condition_format: (
Callable[[List[Condition]], List[Dict[str, Any]]] | None
) = normalize_conditions_per_column,
measurement_mapping_format: (
Comment thread
Ahalya-ni marked this conversation as resolved.
Resolved
Callable[[List[MeasurementMappingItem]], List[Dict[str, Any]]] | None
) = normalize_measurement_mappings_per_column,
) -> pd.DataFrame:
"""Creates a Pandas DataFrame for the specs.

Expand All @@ -120,23 +199,52 @@ def convert_specs_to_dataframe(
If condition value is needed as a string summary of condition data, the public method
`summarize_conditions_as_a_string` can be provided as this callback function.
If None is passed, conditions will not be included in the dataframe.
measurement_mapping_format: A callback function which takes in a list of measurement mapping
items of a spec and returns a list of dictionary of measurement mapping
data. Dataframe rows will be constructed based on these list of
dictionaries. Each dictionary in the list indicates a row. If there is
more than one dictionary in the list, it will be considered as a new
row and other spec column data will be duplicated. Keys will be used as
the dataframe column header and values will be used as the row cells
for the respective column header.
If not passed, each mapping item will be split into the indexed columns
`measurement_mapping[<index>].filter` and
`measurement_mapping[<index>].result_filter`.
If measurement mapping is needed as one row per mapping item, the public
method `normalize_measurement_mappings_per_row` can be provided as the
callback function.
If measurement mapping is needed as a string summary, the public method
`summarize_measurement_mappings_as_a_string` can be provided as this
callback function.
If None is passed, measurement mappings will not be included in the dataframe.

Returns:
A Pandas DataFrame with the each spec fields having a separate column.
Following fields are split into sub-columns.
- conditions: format of the condition columns are decided by the `condition_format`
argument of this function.
- measurement_mapping: format of the measurement mapping columns are decided by the
`measurement_mapping_format` argument of this function.
- Properties: All the unique properties across all specs will be split into separate columns.
For example, properties.property1, properties.property2, etc.
"""
specs_dict = [
__convert_spec_to_dict(spec=spec, condition=condition)
__convert_spec_to_dict(
spec=spec,
condition=condition,
measurement_mapping=measurement_mapping,
)
for spec in specs
for condition in (
condition_format(spec.conditions)
if (spec.conditions and condition_format)
else [{}]
)
for measurement_mapping in (
(measurement_mapping_format(spec.measurement_mapping) or [{}])
if (spec.measurement_mapping and measurement_mapping_format)
else [{}]
)
]

specs_dataframe = pd.json_normalize(specs_dict)
Expand All @@ -147,29 +255,54 @@ def convert_specs_to_dataframe(


def __convert_spec_to_dict(
spec: Specification, condition: Dict[str, Any]
spec: Specification,
condition: Dict[str, Any],
measurement_mapping: Dict[str, Any],
) -> Dict[str, Any]:
"""Converts a spec into dictionary.

Args:
spec: Spec object.
condition: Condition as a dictionary which is added to the output spec dictionary.
measurement_mapping: Measurement mapping as a dictionary which is added to the output spec dictionary.

Returns:
Spec as a dictionary with the provided condition dictionary included.
Spec as a dictionary with the provided condition and measurement mapping dictionaries included.
"""
return {
**{
key: value
for key, value in vars(spec).items()
if key not in ["type", "limit", "conditions"]
if key not in ["type", "limit", "conditions", "measurement_mapping"]
},
**(__serialize_type(spec.type) if spec.type else {}),
**(__serialize_limits(spec.limit) if spec.limit else {}),
**{key: value for key, value in measurement_mapping.items()},
**{key: value for key, value in condition.items()},
}


def __serialize_measurement_mapping_fields(
measurement_mapping: MeasurementMappingItem,
) -> Dict[str, str]:
"""Get the fields of a measurement mapping item that have a value.

Args:
measurement_mapping: Measurement mapping item of a spec.

Returns:
Dictionary with the keys "filter" and "result_filter" when their values are not None.
"""
return {
key: value
for key, value in (
("filter", measurement_mapping.filter),
("result_filter", measurement_mapping.result_filter),
)
if value is not None
}


def __serialize_limits(limit: SpecificationLimit) -> Dict[str, str]:
"""Serialize limit into limit.min, limit.typical and limit.max.

Expand Down
Loading
Loading