MPT-17888: add first-level field annotations to Parameter and ParameterGroup models (#230)

## Summary

Add type-annotated fields to the `Parameter` and `ParameterGroup` model
classes derived from the OpenAPI spec (`ParameterDefinition` and
`ParameterGroup` schemas respectively).

## Changes

### `Parameter` model (`products_parameters.py`)
Fields from the `ParameterDefinition` schema:
- Primitives: `name`, `description`, `scope`, `phase`, `context`,
`type`, `status`, `external_id`, `display_order`
- Nested objects: `group`, `product`, `constraints`, `audit`, `options`

### `ParameterGroup` model (`products_parameter_groups.py`)
Fields from the `ParameterGroup` schema:
- Primitives: `name`, `label`, `description`, `display_order`,
`default`, `parameter_count`
- Nested objects: `product`, `audit`

## Notes
- All fields are typed as `T | None` since RQL `select` can exclude any
field from the API response
- Nested objects are typed as `BaseModel | None` (no dedicated sub-model
classes needed at this level)
- Unit tests extended to cover field access, `to_dict()` round-trip,
nested `BaseModel` typing, and optional field absence

Author: albertsola

.gitignore

@@ -166,7 +166,7 @@ cython_debug/
 .DS_Store
 .ruff_cache
 .idea
-
+.openapi/
 # Makefile
 make/local.mk
 

mpt_api_client/resources/catalog/products_parameter_groups.py

@@ -6,10 +6,31 @@
     ManagedResourceMixin,
 )
 from mpt_api_client.models import Model
+from mpt_api_client.models.model import BaseModel
 
 
 class ParameterGroup(Model):
-    """Parameter Group resource."""
+    """Parameter Group resource.
+
+    Attributes:
+        name: Parameter group name.
+        label: Display label for the parameter group.
+        description: Parameter group description.
+        display_order: Display order of the group.
+        default: Whether this is the default parameter group.
+        parameter_count: Number of parameters in this group.
+        product: Reference to the product this group belongs to.
+        audit: Audit information (created, updated events).
+    """
+
+    name: str | None
+    label: str | None
+    description: str | None
+    display_order: int | None
+    default: bool | None
+    parameter_count: int | None
+    product: BaseModel | None
+    audit: BaseModel | None
 
 
 class ParameterGroupsServiceConfig:

mpt_api_client/resources/catalog/products_parameters.py

@@ -6,10 +6,43 @@
     ManagedResourceMixin,
 )
 from mpt_api_client.models import Model
+from mpt_api_client.models.model import BaseModel
 
 
 class Parameter(Model):
-    """Parameter resource."""
+    """Parameter resource.
+
+    Attributes:
+        name: Parameter name.
+        description: Parameter description.
+        scope: Parameter scope (e.g. Agreement, Item, Request, Subscription, Order, Asset).
+        phase: Parameter phase (e.g. Configuration, Order, Fulfillment).
+        context: Parameter context (e.g. None, Purchase, Change, Configuration, Termination).
+        type: Parameter type (e.g. SingleLineText, MultiLineText, Address, etc.).
+        status: Parameter status.
+        external_id: External identifier for the parameter.
+        display_order: Display order of the parameter.
+        group: Reference to the parameter group.
+        product: Reference to the product this parameter belongs to.
+        constraints: Parameter constraints (required, hidden, readonly).
+        audit: Audit information (created, updated events).
+        options: Type-specific parameter options.
+    """
+
+    name: str | None
+    description: str | None
+    scope: str | None
+    phase: str | None
+    context: str | None
+    type: str | None
+    status: str | None
+    external_id: str | None
+    display_order: int | None
+    group: BaseModel | None
+    product: BaseModel | None
+    constraints: BaseModel | None
+    audit: BaseModel | None
+    options: BaseModel | None
 
 
 class ParametersServiceConfig:

tests/unit/resources/catalog/test_products_parameter_groups.py

@@ -1,7 +1,9 @@
 import pytest
 
+from mpt_api_client.models.model import BaseModel
 from mpt_api_client.resources.catalog.products_parameter_groups import (
     AsyncParameterGroupsService,
+    ParameterGroup,
     ParameterGroupsService,
 )
 
@@ -20,6 +22,24 @@ def async_parameter_groups_service(async_http_client):
     )
 
 
+@pytest.fixture
+def parameter_group_data():
+    return {
+        "id": "GRP-001",
+        "name": "General",
+        "label": "General Settings",
+        "description": "General configuration parameters",
+        "displayOrder": 1,
+        "default": True,
+        "parameterCount": 5,
+        "product": {"id": "PRD-001", "name": "My Product"},
+        "audit": {
+            "created": {"at": "2024-01-01T00:00:00Z"},
+            "updated": {"at": "2024-01-02T00:00:00Z"},
+        },
+    }
+
+
 def test_endpoint(parameter_groups_service):
     result = parameter_groups_service.path == "/public/v1/catalog/products/PRD-001/parameter-groups"
 
@@ -47,3 +67,33 @@ def test_async_methods_present(async_parameter_groups_service, method):
     result = hasattr(async_parameter_groups_service, method)
 
     assert result is True
+
+
+def test_parameter_group_primitive_fields(parameter_group_data):
+    result = ParameterGroup(parameter_group_data)
+
+    assert result.to_dict() == parameter_group_data
+
+
+def test_parameter_group_nested_field_types(parameter_group_data):
+    result = ParameterGroup(parameter_group_data)
+
+    assert isinstance(result.product, BaseModel)
+    assert isinstance(result.audit, BaseModel)
+
+
+def test_parameter_group_nested_field_values(parameter_group_data):
+    result = ParameterGroup(parameter_group_data)
+
+    assert result.product.id == "PRD-001"
+    assert result.product.name == "My Product"
+
+
+def test_parameter_group_optional_fields_absent():
+    result = ParameterGroup({"id": "GRP-002"})
+
+    assert result.id == "GRP-002"
+    assert not hasattr(result, "name")
+    assert not hasattr(result, "label")
+    assert not hasattr(result, "product")
+    assert not hasattr(result, "audit")

tests/unit/resources/catalog/test_products_parameters.py

@@ -1,7 +1,9 @@
 import pytest
 
+from mpt_api_client.models.model import BaseModel
 from mpt_api_client.resources.catalog.products_parameters import (
     AsyncParametersService,
+    Parameter,
     ParametersService,
 )
 
@@ -18,6 +20,30 @@ def async_parameters_service(async_http_client):
     )
 
 
+@pytest.fixture
+def parameter_data():
+    return {
+        "id": "PRM-001",
+        "name": "Tenant Name",
+        "description": "The tenant name",
+        "scope": "Agreement",
+        "phase": "Configuration",
+        "context": "Purchase",
+        "type": "SingleLineText",
+        "status": "Active",
+        "externalId": "ext-001",
+        "displayOrder": 1,
+        "group": {"id": "GRP-001", "name": "General"},
+        "product": {"id": "PRD-001", "name": "My Product"},
+        "constraints": {"required": True, "hidden": False, "readonly": False},
+        "audit": {
+            "created": {"at": "2024-01-01T00:00:00Z"},
+            "updated": {"at": "2024-01-02T00:00:00Z"},
+        },
+        "options": {"placeholder": "Enter tenant name"},
+    }
+
+
 def test_endpoint(parameters_service):
     result = parameters_service.path == "/public/v1/catalog/products/PRD-001/parameters"
 
@@ -42,3 +68,39 @@ def test_async_methods_present(async_parameters_service, method):
     result = hasattr(async_parameters_service, method)
 
     assert result is True
+
+
+def test_parameter_primitive_fields(parameter_data):
+    result = Parameter(parameter_data)
+
+    assert result.to_dict() == parameter_data
+
+
+def test_parameter_nested_fields_are_base_models(parameter_data):
+    result = Parameter(parameter_data)
+
+    assert isinstance(result.group, BaseModel)
+    assert isinstance(result.product, BaseModel)
+    assert isinstance(result.constraints, BaseModel)
+    assert isinstance(result.audit, BaseModel)
+    assert isinstance(result.options, BaseModel)
+
+
+def test_parameter_nested_field_values(parameter_data):
+    result = Parameter(parameter_data)
+
+    assert result.group.id == "GRP-001"
+    assert result.group.name == "General"
+    assert result.product.id == "PRD-001"
+    assert result.constraints.required is True
+    assert result.constraints.hidden is False
+
+
+def test_parameter_optional_fields_absent():
+    result = Parameter({"id": "PRM-002"})
+
+    assert result.id == "PRM-002"
+    assert not hasattr(result, "name")
+    assert not hasattr(result, "scope")
+    assert not hasattr(result, "group")
+    assert not hasattr(result, "options")