FinOps SDK Step 2: paginated list iterator + metadata reads

- records.list(entity_set, *, filter, select, expand, orderby, top,
  page_size, cross_company): generator over @odata.nextLink with
  client-side top cap, Prefer: odata.maxpagesize header, and the
  FinOps-specific cross-company=true switch (verified live against
  Aurora aurorabapenvdc9e7 -- per-company default returns 0 rows
  for CustomerGroups, cross_company=True paginates correctly).

- New operations.metadata namespace (read-only):
    list_data_entities / get_data_entity
    list_public_entities / get_public_entity
    list_public_enumerations / get_public_enumeration
  URLs live at /metadata/* (NOT under /data/). Metadata controllers
  reject \ with HTTP 400, so the SDK intentionally does not
  expose select on these methods. \ is sent server-side but
  enforced client-side because the controllers currently ignore it.

- 20 new unit tests (test_records_list.py: 11, test_metadata.py: 9)
  covering pagination, query-option emission, top short-circuit,
  cross-company flag, OData single-quote escaping, empty-name
  validation, and nextLink follow-through. Full pytest sweep:
  1369 passed, 0 failed.

- Live verified end-to-end against
  https://aurorabapenvdc9e7.operations.int.dynamics.com (legal entity
  'dat'): all six smoketest phases green including typed
  FinOpsNotFoundError mapping for missing metadata names.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: riverma12

src/PowerPlatform/FinOps/client.py

@@ -6,7 +6,7 @@
 
 from ._auth import TokenProvider
 from ._http import HttpClient
-from .operations import RecordOperations
+from .operations import MetadataOperations, RecordOperations
 
 if TYPE_CHECKING:  # pragma: no cover
     from azure.core.credentials import TokenCredential
@@ -65,6 +65,7 @@ def __init__(
 
         # Operation namespaces.
         self.records = RecordOperations(self)
+        self.metadata = MetadataOperations(self)
 
     # -- accessors ------------------------------------------------------
 

src/PowerPlatform/FinOps/operations/__init__.py

@@ -1,4 +1,5 @@
 """Operations namespaces for the FinOps SDK."""
+from .metadata import MetadataOperations
 from .records import RecordOperations
 
-__all__ = ["RecordOperations"]
+__all__ = ["MetadataOperations", "RecordOperations"]

src/PowerPlatform/FinOps/operations/metadata.py

@@ -0,0 +1,158 @@
+"""Metadata read operations for the FinOps SDK.
+
+This is **Step 2** of the FinOps SDK roadmap captured in
+``FinOps-SDK-Plan.docx``. It wraps the read-only metadata surface exposed
+by the FinOps Platform under ``/metadata/...``:
+
+==============================  ==============================================
+HTTP                            SDK call
+==============================  ==============================================
+``GET /metadata/DataEntities``        ``client.metadata.list_data_entities(...)``
+``GET /metadata/DataEntities('N')``   ``client.metadata.get_data_entity('N')``
+``GET /metadata/PublicEntities``      ``client.metadata.list_public_entities(...)``
+``GET /metadata/PublicEntities('N')`` ``client.metadata.get_public_entity('N')``
+``GET /metadata/PublicEnumerations`` ``client.metadata.list_public_enumerations()``
+==============================  ==============================================
+
+These verbs are backed by ``DataEntitiesController`` and sibling controllers in
+the FinOps Platform under
+``Source/Platform/Integration/Services/WebApi/Metadata/Source/Controllers/``.
+
+These endpoints are read-only by design — there is no runtime metadata-write
+API in FinOps (schema is authored in X++ and built into the model layer; see
+``FinOps-SDK-Plan.docx`` §7).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator, Optional
+from urllib.parse import quote
+
+from ..errors import FinOpsError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..client import FinOpsClient
+
+
+class MetadataOperations:
+    """Read-only metadata operations on the FinOps ``/metadata`` surface.
+
+    Obtain via ``FinOpsClient.metadata`` — do not instantiate directly.
+    """
+
+    def __init__(self, client: "FinOpsClient") -> None:
+        self._client = client
+
+    # ------------------------------------------------------------------ #
+    # /metadata/DataEntities                                             #
+    # ------------------------------------------------------------------ #
+    def list_data_entities(
+        self,
+        *,
+        filter: Optional[str] = None,
+        top: Optional[int] = None,
+    ) -> Iterator[dict]:
+        """``GET /metadata/DataEntities`` — yield every public data entity descriptor.
+
+        Returns one row at a time, transparently following the
+        ``@odata.nextLink`` continuation token.
+
+        .. note::
+           The metadata controllers do **not** support ``$select`` (the server
+           replies HTTP 400). ``$top`` is accepted but currently ignored
+           server-side, so this SDK enforces ``top`` as a client-side cap.
+        """
+        yield from self._paginate("DataEntities", filter=filter, top=top)
+
+    def get_data_entity(self, name: str) -> dict:
+        """``GET /metadata/DataEntities('Name')`` — single entity descriptor."""
+        if not name:
+            raise ValueError("entity name is required")
+        url = f"{self._metadata_url()}/DataEntities('{_escape(name)}')"
+        return self._client._http.request("GET", url, expected=(200,)).json()
+
+    # ------------------------------------------------------------------ #
+    # /metadata/PublicEntities                                           #
+    # ------------------------------------------------------------------ #
+    def list_public_entities(
+        self,
+        *,
+        filter: Optional[str] = None,
+        top: Optional[int] = None,
+    ) -> Iterator[dict]:
+        """``GET /metadata/PublicEntities`` — yield every public entity (with column metadata).
+
+        See :meth:`list_data_entities` for ``$select``/``$top`` caveats.
+        """
+        yield from self._paginate("PublicEntities", filter=filter, top=top)
+
+    def get_public_entity(self, name: str) -> dict:
+        """``GET /metadata/PublicEntities('Name')`` — single entity with column metadata."""
+        if not name:
+            raise ValueError("entity name is required")
+        url = f"{self._metadata_url()}/PublicEntities('{_escape(name)}')"
+        return self._client._http.request("GET", url, expected=(200,)).json()
+
+    # ------------------------------------------------------------------ #
+    # /metadata/PublicEnumerations                                       #
+    # ------------------------------------------------------------------ #
+    def list_public_enumerations(
+        self,
+        *,
+        filter: Optional[str] = None,
+        top: Optional[int] = None,
+    ) -> Iterator[dict]:
+        """``GET /metadata/PublicEnumerations`` — yield every public enum descriptor."""
+        yield from self._paginate("PublicEnumerations", filter=filter, top=top)
+
+    def get_public_enumeration(self, name: str) -> dict:
+        """``GET /metadata/PublicEnumerations('Name')`` — single enum descriptor."""
+        if not name:
+            raise ValueError("enumeration name is required")
+        url = f"{self._metadata_url()}/PublicEnumerations('{_escape(name)}')"
+        return self._client._http.request("GET", url, expected=(200,)).json()
+
+    # ------------------------------------------------------------------ #
+    # internals                                                          #
+    # ------------------------------------------------------------------ #
+    def _metadata_url(self) -> str:
+        return f"{self._client.environment_url}/metadata"
+
+    def _paginate(
+        self,
+        collection: str,
+        *,
+        filter: Optional[str] = None,
+        top: Optional[int] = None,
+    ) -> Iterator[dict]:
+        params: dict = {}
+        if filter:
+            params["$filter"] = filter
+        if top is not None:
+            if top <= 0:
+                return
+            # Server currently ignores $top on /metadata/* but sending it is
+            # harmless and lets us upgrade transparently if/when it lands.
+            params["$top"] = str(top)
+
+        url: Optional[str] = f"{self._metadata_url()}/{collection}"
+        request_params: Optional[dict] = params or None
+        yielded = 0
+        while url:
+            resp = self._client._http.request(
+                "GET", url, params=request_params, expected=(200,)
+            )
+            payload = resp.json()
+            for row in payload.get("value", []):
+                if top is not None and yielded >= top:
+                    return
+                yield row
+                yielded += 1
+            url = payload.get("@odata.nextLink")
+            request_params = None
+
+
+def _escape(name: str) -> str:
+    if "'" in name:
+        # OData v4 string literal escape: single quotes are doubled.
+        return name.replace("'", "''")
+    return name

src/PowerPlatform/FinOps/operations/records.py

@@ -34,7 +34,7 @@
 
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, Mapping, Optional, Union
+from typing import TYPE_CHECKING, Any, Iterator, Mapping, Optional, Sequence, Union
 from urllib.parse import quote
 
 from ..errors import FinOpsError
@@ -121,8 +121,100 @@ def get(
         return resp.json()
 
     # ------------------------------------------------------------------ #
-    # UPDATE                                                             #
+    # LIST (paginated)                                                   #
     # ------------------------------------------------------------------ #
+    def list(
+        self,
+        entity_set: str,
+        *,
+        filter: Optional[str] = None,
+        select: Optional[Sequence[str]] = None,
+        expand: Optional[Sequence[str]] = None,
+        orderby: Optional[Union[str, Sequence[str]]] = None,
+        top: Optional[int] = None,
+        page_size: Optional[int] = None,
+        cross_company: bool = False,
+    ) -> Iterator[dict]:
+        """``GET /data/{entity_set}`` — yield rows lazily across all pages.
+
+        Transparently follows the ``@odata.nextLink`` continuation token
+        emitted by FinOps OData and yields one row dict at a time. Stops
+        after ``top`` rows when given (server is told via ``$top``; client
+        also caps just in case the server ignores it).
+
+        Parameters
+        ----------
+        entity_set:
+            FinOps OData entity set name (e.g. ``"CustomersV3"``).
+        filter:
+            Raw OData ``$filter`` expression. Callers are responsible for
+            quoting; the SDK will not try to parse it. A typed query builder
+            is on the roadmap (see ``FinOps-SDK-Plan.docx`` §8 Phase 2).
+        select:
+            Column names for ``$select``.
+        expand:
+            Navigation properties for ``$expand``.
+        orderby:
+            Either a single OData ordering clause (``"CreatedDateTime desc"``)
+            or a list of them.
+        top:
+            Hard cap on rows. Sent server-side as ``$top`` and enforced
+            client-side as a defensive stop.
+        page_size:
+            Optional ``Prefer: odata.maxpagesize=N`` hint to ask the server
+            for smaller pages — useful when the dataset is large and the
+            caller is paging memory-sensitively.
+        cross_company:
+            When ``True``, sends the FinOps-specific ``cross-company=true``
+            query parameter so rows from every legal entity (``dataAreaId``)
+            are returned. Default is ``False``, which mirrors the FinOps
+            OData default of scoping to the caller's default company.
+
+        Yields
+        ------
+        dict
+            One OData row at a time.
+        """
+        params: dict = {}
+        if cross_company:
+            params["cross-company"] = "true"
+        if filter:
+            params["$filter"] = filter
+        if select:
+            params["$select"] = ",".join(select)
+        if expand:
+            params["$expand"] = ",".join(expand)
+        if orderby:
+            params["$orderby"] = orderby if isinstance(orderby, str) else ",".join(orderby)
+        if top is not None:
+            if top <= 0:
+                return
+            params["$top"] = str(top)
+
+        headers: Optional[dict] = None
+        if page_size is not None:
+            if page_size <= 0:
+                raise ValueError("page_size must be positive")
+            headers = {"Prefer": f"odata.maxpagesize={int(page_size)}"}
+
+        url: Optional[str] = self._collection_url(entity_set)
+        request_params: Optional[dict] = params or None
+        yielded = 0
+        while url:
+            resp = self._client._http.request(
+                "GET", url, params=request_params, headers=headers, expected=(200,)
+            )
+            payload = resp.json()
+            for row in payload.get("value", []):
+                if top is not None and yielded >= top:
+                    return
+                yield row
+                yielded += 1
+            url = payload.get("@odata.nextLink")
+            # The nextLink already encodes all of the original $-options.
+            request_params = None
+
+
     def update(
         self,
         entity_set: str,

step2_smoketest.py

@@ -0,0 +1,103 @@
+"""Step 2 live smoketest — list pagination + metadata reads.
+
+Run from the C:\\finops-crud-demo .venv with the SDK installed editable.
+Requires: az login (see README), then `python step2_smoketest.py`.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+from azure.identity import AzureCliCredential
+
+from PowerPlatform.FinOps import FinOpsClient
+
+
+def main() -> int:
+    env_url = os.environ.get(
+        "FNO_ENV_URL", "https://aurorabapenvdc9e7.operations.int.dynamics.com"
+    )
+    tenant_id = os.environ.get(
+        "FNO_TENANT_ID", "4abc24ea-2d0b-4011-87d4-3de32ca1e9cc"
+    )
+
+    print("=" * 72)
+    print(f" Step 2 smoketest against {env_url}")
+    print("=" * 72)
+
+    cred = AzureCliCredential(tenant_id=tenant_id)
+    with FinOpsClient(env_url, cred) as client:
+
+        # ---- records.list with $top + $select ----
+        print("\n[1] records.list(LegalEntities, top=3, select=[LegalEntityId, Name])")
+        rows = list(
+            client.records.list(
+                "LegalEntities",
+                select=["LegalEntityId", "Name"],
+                top=3,
+            )
+        )
+        for r in rows:
+            print(f"    -> {r.get('LegalEntityId')!r}  {r.get('Name')!r}")
+        print(f"    => yielded {len(rows)} rows (top=3)")
+
+        # ---- records.list paginating across many CustomerGroups ----
+        print("\n[2] records.list(CustomerGroups, cross_company=True, page_size=10) iterate first 25")
+        cg_iter = client.records.list(
+            "CustomerGroups", cross_company=True, page_size=10
+        )
+        first25 = []
+        for row in cg_iter:
+            first25.append(row.get("CustomerGroupId"))
+            if len(first25) >= 25:
+                break
+        print(f"    -> first IDs: {first25[:10]} ...")
+        print(f"    => collected {len(first25)} rows across pages of 10")
+
+        # ---- metadata.list_data_entities ----
+        print("\n[3] metadata.list_data_entities(top=5)  (server ignores $top, SDK caps client-side)")
+        de_rows = list(client.metadata.list_data_entities(top=5))
+        for r in de_rows:
+            print(f"    -> {r.get('Name')}  ({r.get('PublicEntityName')})")
+        print(f"    => yielded {len(de_rows)} rows")
+
+        # ---- metadata.get_data_entity for one we know exists ----
+        # `Name` is the X++ entity name (e.g. `AbbreviationsEntity`), not the
+        # public OData entity set name. We pick whatever name came back from
+        # phase 3 above so the smoketest is self-bootstrapping.
+        if not de_rows:
+            print("\n[4] SKIPPED — phase 3 yielded no rows")
+        else:
+            target_name = de_rows[0]["Name"]
+            print(f"\n[4] metadata.get_data_entity({target_name!r})")
+            de = client.metadata.get_data_entity(target_name)
+            print(
+                f"    -> Name={de.get('Name')!r}  "
+                f"PublicEntityName={de.get('PublicEntityName')!r}  "
+                f"IsReadOnly={de.get('IsReadOnly')}"
+            )
+
+        # ---- typed 404 mapping for missing metadata name ----
+        from PowerPlatform.FinOps.errors import FinOpsNotFoundError
+
+        print("\n[5] metadata.get_data_entity('NoSuchEntityXYZ')  (expecting typed 404)")
+        try:
+            client.metadata.get_data_entity("NoSuchEntityXYZ")
+        except FinOpsNotFoundError as exc:
+            print(f"    -> typed FinOpsNotFoundError raised: status={exc.status_code}")
+        else:  # pragma: no cover
+            raise SystemExit("expected FinOpsNotFoundError")
+
+        # ---- metadata.list_public_enumerations small page ----
+        print("\n[6] metadata.list_public_enumerations(top=3)")
+        for r in client.metadata.list_public_enumerations(top=3):
+            print(f"    -> {r.get('Name')}")
+
+    print("\n" + "=" * 72)
+    print(" STEP 2 SMOKETEST OK")
+    print("=" * 72)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())