Address PR review comments: docstrings, dynamic cap message, dispatch validation

- Fix .. note:: in records.create/update/upsert to mention concurrent dispatch
  when max_workers > 1, not just sequential chunking (comment #1)
- Import _MAX_WORKERS in records.py and build the ValueError message from it
  so the text stays accurate if the cap changes (comment #2)
- Add explicit ValueError in _dispatch_chunks for non-int or < 1 max_workers,
  with three new tests covering zero, negative, and non-int inputs (comments #4/#5)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Abel Milash

src/PowerPlatform/Dataverse/data/_odata.py

@@ -88,6 +88,8 @@ def _dispatch_chunks(fn: Callable, chunks: List, max_workers: int) -> List:
     :param max_workers: Maximum number of concurrent worker threads.
     :return: List of results in chunk submission order.
     """
+    if not isinstance(max_workers, int) or max_workers < 1:
+        raise ValueError(f"max_workers must be a positive integer; got {max_workers!r}")
     if max_workers > _MAX_WORKERS:
         warnings.warn(
             f"max_workers={max_workers} exceeds the maximum of {_MAX_WORKERS}; capping to {_MAX_WORKERS}.",

src/PowerPlatform/Dataverse/operations/records.py

@@ -9,6 +9,7 @@
 
 from ..models.record import Record
 from ..models.upsert import UpsertItem
+from ..data._odata import _MAX_WORKERS
 
 if TYPE_CHECKING:
     from ..client import DataverseClient
@@ -80,10 +81,12 @@ def create(
         :raises TypeError: If ``data`` is not a dict or list[dict].
 
         .. note::
-            Lists exceeding 1,000 records are automatically split into
-            sequential chunks. This is **not atomic** — a failure mid-way
-            may leave earlier chunks applied. Callers that require atomicity
-            should limit input to ≤ 1,000 records.
+            Lists exceeding 1,000 records are automatically split into chunks
+            of up to 1,000 records; dispatched sequentially by default, or
+            concurrently when ``max_workers > 1`` (capped to ``_MAX_WORKERS``).
+            This is **not atomic** — a failure mid-way may leave earlier chunks
+            applied. Callers that require atomicity should limit input to
+            ≤ 1,000 records.
 
         Example:
             Create a single record::
@@ -100,7 +103,9 @@ def create(
                 print(f"Created {len(guids)} accounts")
         """
         if not isinstance(max_workers, int) or max_workers < 1:
-            raise ValueError("max_workers must be a positive integer (1–3; values above 3 are capped at 3)")
+            raise ValueError(
+                f"max_workers must be a positive integer (1–{_MAX_WORKERS}; values above {_MAX_WORKERS} are capped at {_MAX_WORKERS})"
+            )
         with self._client._scoped_odata() as od:
             entity_set = od._entity_set_from_schema_name(table)
             if isinstance(data, dict):
@@ -148,9 +153,11 @@ def update(
             does not match the expected pattern.
 
         .. note::
-            Lists exceeding 1,000 IDs are automatically split into sequential
-            chunks. This is **not atomic** — a failure mid-way may leave
-            earlier chunks applied. Callers that require atomicity should
+            Lists exceeding 1,000 IDs are automatically split into chunks of
+            up to 1,000; dispatched sequentially by default, or concurrently
+            when ``max_workers > 1`` (capped to ``_MAX_WORKERS``). This is
+            **not atomic** — a failure mid-way may leave earlier chunks
+            applied. Callers that require atomicity should
             limit input to ≤ 1,000 IDs.
 
         Example:
@@ -171,7 +178,9 @@ def update(
                 )
         """
         if not isinstance(max_workers, int) or max_workers < 1:
-            raise ValueError("max_workers must be a positive integer (1–3; values above 3 are capped at 3)")
+            raise ValueError(
+                f"max_workers must be a positive integer (1–{_MAX_WORKERS}; values above {_MAX_WORKERS} are capped at {_MAX_WORKERS})"
+            )
         with self._client._scoped_odata() as od:
             if isinstance(ids, str):
                 if not isinstance(changes, dict):
@@ -507,10 +516,12 @@ def upsert(self, table: str, items: List[Union[UpsertItem, Dict[str, Any]]], *,
             dict with ``"alternate_key"`` and ``"record"`` keys.
 
         .. note::
-            Lists exceeding 1,000 items are automatically split into
-            sequential chunks. This is **not atomic** — a failure mid-way
-            may leave earlier chunks applied. Callers that require atomicity
-            should limit input to ≤ 1,000 items.
+            Lists exceeding 1,000 items are automatically split into chunks
+            of up to 1,000; dispatched sequentially by default, or
+            concurrently when ``max_workers > 1`` (capped to ``_MAX_WORKERS``).
+            This is **not atomic** — a failure mid-way may leave earlier chunks
+            applied. Callers that require atomicity should limit input to
+            ≤ 1,000 items.
 
         Example:
             Upsert a single record using ``UpsertItem``::
@@ -566,7 +577,9 @@ def upsert(self, table: str, items: List[Union[UpsertItem, Dict[str, Any]]], *,
             ``{"accountnumber": "ACC-001", "address1_postalcode": "98052"}``.
         """
         if not isinstance(max_workers, int) or max_workers < 1:
-            raise ValueError("max_workers must be a positive integer (1–3; values above 3 are capped at 3)")
+            raise ValueError(
+                f"max_workers must be a positive integer (1–{_MAX_WORKERS}; values above {_MAX_WORKERS} are capped at {_MAX_WORKERS})"
+            )
         if not isinstance(items, list) or not items:
             raise TypeError("items must be a non-empty list of UpsertItem or dicts")
         normalized: List[UpsertItem] = []

tests/unit/data/test_multiple_chunking.py

@@ -1141,6 +1141,21 @@ def test_below_cap_is_not_capped(self):
         results = self._dispatch(lambda c: c, ["x", "y", "z"], max_workers=self._cap - 1)
         self.assertEqual(results, ["x", "y", "z"])
 
+    def test_zero_raises_value_error(self):
+        """max_workers=0 raises ValueError."""
+        with self.assertRaises(ValueError):
+            self._dispatch(lambda c: c, ["a"], max_workers=0)
+
+    def test_negative_raises_value_error(self):
+        """Negative max_workers raises ValueError."""
+        with self.assertRaises(ValueError):
+            self._dispatch(lambda c: c, ["a"], max_workers=-1)
+
+    def test_non_int_raises_value_error(self):
+        """Non-integer max_workers raises ValueError."""
+        with self.assertRaises(ValueError):
+            self._dispatch(lambda c: c, ["a"], max_workers="3")
+
 
 # ---------------------------------------------------------------------------
 # Picklist cache lock: concurrent cold-start