feat: Add and resolve query projection for products and specs respectively (#97)

Co-authored-by: Sam rishi <sam.rishi@solitontech.local>
Co-authored-by: sam-rishi <155733081+sam-rishi@users.noreply.github.com>
Co-authored-by: Sam Rishi <sam.rishi@ni.com>

BREAKING CHANGE: Product and Specification models have been updated
to support projections.
 - Product client changes--
   - `models.Product` now defines all fields as Optional.
   - `ProductClient.create_product`'s `products` parameter is now typed
     as `models.CreateProductRequest`
   - `ProductClient.update_product`'s `products` parameter is now typed
     as `models.UpdateProductRequest`
 - Specifications client changes--
   - `models.Specification` and `models.SpecificationDefinition` now
     define all fields as Optional.
   - `models.QuerySpecifications` has been renamed `models.PagedSpecifications`
     to better align to other clients.
   - `models.CreateSpecificationeRequest.specs` is now typed as `models.CreateSpecificationsRequestObject`
     instead of `models.SpecificationDefinition`
   - `models.UpdateSpecificationeRequest.specs` is now typed as `models.UpdateSpecificationsRequestObject`
     instead of `models.Specification`

Author: shri2k2

examples/product/products.py

@@ -1,8 +1,9 @@
 from nisystemlink.clients.core import HttpConfiguration
 from nisystemlink.clients.product import ProductClient
 from nisystemlink.clients.product.models import (
-    Product,
+    CreateProductRequest,
     ProductField,
+    ProductOrderBy,
     QueryProductsRequest,
     QueryProductValuesRequest,
 )
@@ -14,14 +15,14 @@
 def create_some_products():
     """Create two example products on your server."""
     new_products = [
-        Product(
+        CreateProductRequest(
             part_number="Example 123 AA",
             name=name,
             family=family,
             keywords=["original keyword"],
             properties={"original property key": "yes"},
         ),
-        Product(
+        CreateProductRequest(
             part_number="Example 123 AA1",
             name=name,
             family=family,
@@ -58,9 +59,9 @@ def create_some_products():
 query_request = QueryProductsRequest(
     filter=f'family="{family}" && name="{name}"',
     return_count=True,
-    order_by=ProductField.FAMILY,
+    order_by=ProductOrderBy.FAMILY,
 )
-response = client.query_products_paged(query_request)
+query_response = client.query_products_paged(query_request)
 
 # Update the first product that you just created and replace the keywords
 updated_product = create_response.products[0]

examples/spec/update_and_delete_specs.py

@@ -56,4 +56,4 @@
 # query all specs
 response = client.query_specs(QuerySpecificationsRequest(product_ids=[product]))
 if response.specs:
-    client.delete_specs(ids=[spec.id for spec in response.specs])
+    client.delete_specs(ids=[spec.id for spec in response.specs if spec.id])

nisystemlink/clients/product/_product_client.py

@@ -5,12 +5,14 @@
 from nisystemlink.clients import core
 from nisystemlink.clients.core._uplink._base_client import BaseClient
 from nisystemlink.clients.core._uplink._methods import delete, get, post
-from nisystemlink.clients.product.models import Product
-from uplink import Field, Query, returns
+from uplink import Field, Query, retry, returns
 
 from . import models
 
 
+@retry(
+    when=retry.when.status([408, 429, 502, 503, 504]), stop=retry.stop.after_attempt(5)
+)
 class ProductClient(BaseClient):
     def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
         """Initialize an instance.
@@ -30,7 +32,7 @@ def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
 
     @post("products", args=[Field("products")])
     def create_products(
-        self, products: List[Product]
+        self, products: List[models.CreateProductRequest]
     ) -> models.CreateProductsPartialSuccess:
         """Creates one or more products and returns errors for failed creations.
 
@@ -128,7 +130,7 @@ def query_product_values(
 
     @post("update-products", args=[Field("products"), Field("replace")])
     def update_products(
-        self, products: List[Product], replace: bool = False
+        self, products: List[models.UpdateProductRequest], replace: bool = False
     ) -> models.CreateProductsPartialSuccess:
         """Updates a list of products with optional field replacement.
 

nisystemlink/clients/product/models/__init__.py

@@ -1,11 +1,14 @@
-from ._product import Product
 from ._create_products_partial_success import CreateProductsPartialSuccess
 from ._delete_products_partial_success import DeleteProductsPartialSuccess
 from ._paged_products import PagedProducts
 from ._query_products_request import (
-    QueryProductsRequest,
     ProductField,
+    ProductOrderBy,
+    ProductProjection,
+    QueryProductsRequest,
     QueryProductValuesRequest,
 )
+from ._product import Product
+from ._product_request import CreateProductRequest, UpdateProductRequest
 
 # flake8: noqa

nisystemlink/clients/product/models/_create_products_partial_success.py

@@ -2,20 +2,21 @@
 
 from nisystemlink.clients.core import ApiError
 from nisystemlink.clients.core._uplink._json_model import JsonModel
-from nisystemlink.clients.product.models import Product
+from nisystemlink.clients.product.models._product import Product
+from nisystemlink.clients.product.models._product_request import CreateProductRequest
 
 
 class CreateProductsPartialSuccess(JsonModel):
     products: List[Product]
     """The list of products that were successfully created."""
 
-    failed: Optional[List[Product]] = None
+    failed: Optional[List[CreateProductRequest]]
     """The list of products that were not created.
 
     If this is `None`, then all products were successfully created.
     """
 
-    error: Optional[ApiError] = None
+    error: Optional[ApiError]
     """Error messages for products that were not created.
 
     If this is `None`, then all products were successfully created.

nisystemlink/clients/product/models/_paged_products.py

@@ -1,11 +1,13 @@
 from typing import List, Optional
 
 from nisystemlink.clients.core._uplink._with_paging import WithPaging
-from nisystemlink.clients.product.models import Product
+from nisystemlink.clients.product.models._product import Product
 
 
 class PagedProducts(WithPaging):
-    """The response for a Products query containing matched products."""
+    """The response containing the list of products, total count of products and the continuation
+    token if applicable.
+    """
 
     products: List[Product]
     """A list of all the products in this page."""

nisystemlink/clients/product/models/_product.py

@@ -10,7 +10,7 @@ class Product(JsonModel):
     id: Optional[str]
     """The globally unique id of the product."""
 
-    part_number: str
+    part_number: Optional[str]
     """The part number is the unique identifier of a product within a single org.
 
     Usually the part number refers to a specific revision or version of a given product."""

nisystemlink/clients/product/models/_product_request.py

@@ -0,0 +1,48 @@
+from typing import Dict, List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+
+class BaseProductRequest(JsonModel):
+    """Contains information about a product."""
+
+    name: Optional[str]
+    """The name of the product.
+
+    Usually the name is used to refer to several part numbers that all have the same name but
+    different revisions or versions.
+    """
+
+    family: Optional[str]
+    """The family that that this product belongs to.
+
+    Usually the family is a grouping above product name. A family usually has multiple product
+    names within it.
+    """
+
+    file_ids: Optional[List[str]]
+    """A list of file ids that are attached to this product."""
+
+    keywords: Optional[List[str]]
+    """A list of keywords that categorize this product."""
+
+    properties: Optional[Dict[str, str]]
+    """A list of custom properties for this product."""
+
+    workspace: Optional[str]
+    """The id of the workspace that this product belongs to."""
+
+
+class CreateProductRequest(BaseProductRequest):
+
+    part_number: str
+    """The part number is the unique identifier of a product within a single org.
+
+    Usually the part number refers to a specific revision or version of a given product."""
+
+
+class UpdateProductRequest(BaseProductRequest):
+    """This is the request model to update a product."""
+
+    id: str
+    """The globally unique id of the product."""

nisystemlink/clients/product/models/_query_products_request.py

@@ -5,7 +5,7 @@
 from pydantic import Field
 
 
-class ProductField(str, Enum):
+class ProductOrderBy(str, Enum):
     """The valid ways to order a product query."""
 
     ID = "ID"
@@ -15,6 +15,32 @@ class ProductField(str, Enum):
     UPDATED_AT = "UPDATED_AT"
 
 
+class ProductField(str, Enum):
+    """An enumeration of product fields for which the values can be queried for."""
+
+    ID = "ID"
+    FAMILY = "FAMILY"
+    PART_NUMBER = "PART_NUMBER"
+    NAME = "NAME"
+    UPDATED_AT = "UPDATED_AT"
+
+
+class ProductProjection(str, Enum):
+    """An enumeration of all fields in a Product. These are used to project the required fields
+    from the API response.
+    """
+
+    ID = "ID"
+    FAMILY = "FAMILY"
+    PART_NUMBER = "PART_NUMBER"
+    NAME = "NAME"
+    UPDATED_AT = "UPDATED_AT"
+    WORKSPACE = "WORKSPACE"
+    KEYWORDS = "KEYWORDS"
+    PROPERTIES = "PROPERTIES"
+    FILE_IDS = "FILE_IDS"
+
+
 class QueryProductsBase(JsonModel):
     filter: Optional[str] = None
     """
@@ -50,7 +76,7 @@ class QueryProductsBase(JsonModel):
 
 class QueryProductsRequest(QueryProductsBase):
 
-    order_by: Optional[ProductField] = Field(None, alias="orderBy")
+    order_by: Optional[ProductOrderBy] = Field(None, alias="orderBy")
     """Specifies the fields to use to sort the products.
 
     By default, products are sorted by `id`
@@ -61,11 +87,21 @@ class QueryProductsRequest(QueryProductsBase):
 
     By default, this value is `false` and products are sorted in ascending order.
     """
+
+    projection: Optional[List[ProductProjection]] = None
+    """Specifies the product fields to project.
+
+    When a field value is given here, the corresponding field will be present in all returned products,
+    and all unspecified fields will be excluded. If no projection is specified, all product fields
+    will be returned.
+    """
+
     take: Optional[int] = None
     """Maximum number of products to return in the current API response.
 
     Uses the default if the specified value is negative. The default value is `1000` products.
     """
+
     continuation_token: Optional[str] = None
     """Allows users to continue the query at the next product that matches the given criteria.
 

nisystemlink/clients/product/utilities/_file_utilities.py

@@ -2,7 +2,9 @@
 
 from nisystemlink.clients.product._product_client import ProductClient
 from nisystemlink.clients.product.models._paged_products import PagedProducts
-from nisystemlink.clients.product.models._product import Product
+from nisystemlink.clients.product.models._product import (
+    Product,
+)
 from nisystemlink.clients.product.models._query_products_request import (
     QueryProductsRequest,
 )

nisystemlink/clients/spec/_spec_client.py

@@ -5,11 +5,14 @@
 from nisystemlink.clients import core
 from nisystemlink.clients.core._uplink._base_client import BaseClient
 from nisystemlink.clients.core._uplink._methods import get, post
-from uplink import Field
+from uplink import Field, retry
 
 from . import models
 
 
+@retry(
+    when=retry.when.status([408, 429, 502, 503, 504]), stop=retry.stop.after_attempt(5)
+)
 class SpecClient(BaseClient):
     def __init__(self, configuration: Optional[core.HttpConfiguration] = None):
         """Initialize an instance.
@@ -80,7 +83,7 @@ def delete_specs(
     @post("query-specs")
     def query_specs(
         self, query: models.QuerySpecificationsRequest
-    ) -> models.QuerySpecifications:
+    ) -> models.PagedSpecifications:
         """Queries for specs that match the filters.
 
         Args:

nisystemlink/clients/spec/models/__init__.py

@@ -10,24 +10,25 @@
     CreatedSpecification,
     CreateSpecificationsPartialSuccess,
     CreateSpecificationsRequest,
+    CreateSpecificationsRequestObject,
 )
 from ._delete_specs_request import DeleteSpecificationsPartialSuccess
-from ._query_specs import QuerySpecificationsRequest, QuerySpecifications
+from ._query_specs import (
+    QuerySpecificationsRequest,
+    PagedSpecifications,
+    SpecificationProjection,
+)
 from ._specification import (
     Specification,
-    SpecificationCreation,
     SpecificationDefinition,
     SpecificationLimit,
-    SpecificationServerManaged,
     SpecificationType,
-    SpecificationUpdated,
-    SpecificationUserManaged,
-    SpecificationWithHistory,
 )
 from ._update_specs_request import (
     UpdatedSpecification,
     UpdateSpecificationsPartialSuccess,
     UpdateSpecificationsRequest,
+    UpdateSpecificationsRequestObject,
 )
 
 # flake8: noqa