Office365-REST-Python-Client 3.0.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

office365/sharepoint/listitems/caml/builder.py

@@ -0,0 +1,129 @@
+"""Fluent builder for the CAML ``<View>`` document.
+
+Assembles ``ViewFields``/``Where``/``GroupBy``/``OrderBy``/``RowLimit``/``Scope``
+into a ``ViewXml`` string (or a :class:`CamlQuery`):
+
+    from office365.sharepoint.listitems.caml import Caml, CamlQuery
+    from office365.sharepoint.views.scope import ViewScope
+
+    query = (CamlQuery.builder()
+        .where(Caml.text("Status").eq("Active"))
+        .order_by("Created", ascending=False)
+        .row_limit(2000)
+        .scope(ViewScope.RecursiveAll)
+        .build())
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+from xml.sax.saxutils import quoteattr
+
+from typing_extensions import Self
+
+from office365.sharepoint.listitems.caml.expressions import And, CamlExpr, _as_field_ref, _fold
+from office365.sharepoint.listitems.caml.fields import FieldRef
+from office365.sharepoint.views.scope import ViewScope
+
+if TYPE_CHECKING:
+    from office365.sharepoint.listitems.caml.query import CamlQuery
+
+
+class QueryBuilder:
+    """Fluent builder that renders the CAML ``<View>`` element."""
+
+    def __init__(self) -> None:
+        self._where: Optional[CamlExpr] = None
+        self._order_by: list[FieldRef] = []
+        self._group_by: list[FieldRef] = []
+        self._view_fields: list[FieldRef] = []
+        self._row_limit: Optional[int] = None
+        self._paged = True
+        self._scope: ViewScope = ViewScope.DefaultValue
+
+    def where(self, *conditions: CamlExpr) -> Self:
+        """Set the ``<Where>`` filter (multiple conditions are combined with ``<And>``)."""
+        if conditions:
+            self._where = _fold(And, conditions)
+        return self
+
+    def order_by(self, *fields: Any, ascending: bool = True) -> Self:
+        """Add one or more ``<OrderBy>`` fields (call again to append)."""
+        for field in fields:
+            ref = _as_field_ref(field)
+            self._order_by.append(ref if ref.ascending is not None else ref._copy(ascending=ascending))
+        return self
+
+    def group_by(self, field: Any, *, collapse: bool = True) -> Self:
+        """Add a ``<GroupBy>`` field."""
+        ref = _as_field_ref(field)
+        self._group_by.append(ref if ref.collapse is not None else ref._copy(collapse=collapse))
+        return self
+
+    def view_fields(self, *names: Any) -> Self:
+        """Add ``<ViewFields>`` entries (a ``str``, ``Field`` or ``FieldRef``)."""
+        self._view_fields.extend(_as_field_ref(name) for name in names)
+        return self
+
+    def row_limit(self, top: int, *, paged: bool = True) -> Self:
+        """Set ``<RowLimit>`` (``Paged="TRUE"`` by default)."""
+        self._row_limit = top
+        self._paged = paged
+        return self
+
+    def scope(self, scope: ViewScope) -> Self:
+        """Set the ``Scope`` attribute of ``<View>``."""
+        self._scope = scope
+        return self
+
+    @property
+    def is_paged(self) -> bool:
+        """Whether the query enables server-driven paging (``RowLimit Paged="TRUE"``)."""
+        return self._row_limit is not None and self._paged
+
+    @property
+    def field_refs(self) -> set[str]:
+        """Fields the query filters or sorts on (``ViewFields`` are excluded)."""
+        names: set[str] = set()
+        if self._where is not None:
+            names |= self._where.field_refs
+        for ref in (*self._order_by, *self._group_by):
+            names.add(ref.name)
+        return names
+
+    def to_xml(self) -> str:
+        """Render the CAML ``<View>`` document."""
+        scope = self._scope.value if isinstance(self._scope, ViewScope) else str(self._scope)
+        parts = [f"<View Scope={quoteattr(scope)}>"]
+        if self._view_fields:
+            parts.append("<ViewFields>" + "".join(ref.to_xml() for ref in self._view_fields) + "</ViewFields>")
+        query = self._query_xml()
+        if query:
+            parts.append(query)
+        if self._row_limit is not None:
+            paged = ' Paged="TRUE"' if self._paged else ""
+            parts.append(f"<RowLimit{paged}>{self._row_limit}</RowLimit>")
+        parts.append("</View>")
+        return "".join(parts)
+
+    def _query_xml(self) -> str:
+        query: list[str] = []
+        if self._where is not None:
+            query.append(f"<Where>{self._where.to_xml()}</Where>")
+        if self._group_by:
+            query.append("<GroupBy>" + "".join(ref.to_xml() for ref in self._group_by) + "</GroupBy>")
+        if self._order_by:
+            query.append("<OrderBy>" + "".join(ref.to_xml() for ref in self._order_by) + "</OrderBy>")
+        return "<Query>" + "".join(query) + "</Query>" if query else ""
+
+    def build(self) -> "CamlQuery":
+        """Build a :class:`CamlQuery` (raw ``ViewXml`` + the expression AST)."""
+        from office365.sharepoint.listitems.caml.query import CamlQuery
+
+        query = CamlQuery()
+        query.ViewXml = self.to_xml()
+        query._expr = self
+        return query
+
+    def __repr__(self) -> str:
+        return self.to_xml()

office365/sharepoint/listitems/caml/expressions.py

@@ -0,0 +1,424 @@
+"""Typed CAML query expressions.
+
+Build a ``<Where>`` clause from composable Python objects instead of raw CAML
+strings. Every ``And``/``Or`` node holds **exactly two** children, so any
+combination renders valid, binary-nested CAML (CAML forbids 3+ children):
+
+    from office365.sharepoint.listitems.caml import Caml
+
+    where = (
+        Caml.text("Email").eq("support@google.com")
+        .or_(Caml.text("Email").eq("plus@google.com"))
+        .or_(Caml.text("Title").begins_with("[Google]"))
+    )
+    # identical alternatives:
+    where = Caml.or_(a, b, c)   # variadic -> left-folded binary nesting
+    where = a | b | c           # operators
+
+Logical operators are ``&`` (And), ``|`` (Or), ``~`` (Not); the method forms
+``.and_()/.or_()/.not_()`` read closer to CAML. Python's ``and``/``or``/``not``
+cannot be used (they are keywords) and are rejected at runtime via ``__bool__``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Iterable, Optional, TypeVar
+
+from office365.sharepoint.listitems.caml.fields import FieldRef
+from office365.sharepoint.listitems.caml.values import Value, ValueType, list_property
+from office365.sharepoint.listitems.caml.values import month as _month
+from office365.sharepoint.listitems.caml.values import now as _now
+from office365.sharepoint.listitems.caml.values import today as _today
+from office365.sharepoint.listitems.caml.values import user_id as _user_id
+
+_T = TypeVar("_T")
+
+
+class CamlExpr(ABC):
+    """Base class for CAML query expressions."""
+
+    @abstractmethod
+    def to_xml(self) -> str:
+        """Render this expression as CAML XML."""
+
+    @property
+    def field_refs(self) -> set[str]:
+        """The field names referenced by this expression."""
+        return set()
+
+    def __and__(self, other: "CamlExpr") -> "And":
+        return And(self, other)
+
+    def __or__(self, other: "CamlExpr") -> "Or":
+        return Or(self, other)
+
+    def __invert__(self) -> "Not":
+        return Not(self)
+
+    def and_(self, other: "CamlExpr") -> "And":
+        """Combine with ``other`` using ``<And>`` (same as ``&``)."""
+        return And(self, other)
+
+    def or_(self, other: "CamlExpr") -> "Or":
+        """Combine with ``other`` using ``<Or>`` (same as ``|``)."""
+        return Or(self, other)
+
+    def not_(self) -> "Not":
+        """Negate this expression (same as ``~``)."""
+        return Not(self)
+
+    def __bool__(self) -> bool:
+        raise TypeError(
+            "CAML expressions cannot be used with Python 'and'/'or'/'not'; "
+            "use '&', '|', '~' or the .and_()/.or_()/.not_() methods"
+        )
+
+
+class Comparison(CamlExpr):
+    """A comparison operator element, e.g. ``<Eq><FieldRef/><Value/></Eq>``."""
+
+    def __init__(self, op: str, field: FieldRef, value: Value) -> None:
+        self.op = op
+        self.field = field
+        self.value = value
+
+    @property
+    def field_refs(self) -> set[str]:
+        return {self.field.name}
+
+    def to_xml(self) -> str:
+        return f"<{self.op}>{self.field.to_xml()}{self.value.to_xml()}</{self.op}>"
+
+
+class IsNull(CamlExpr):
+    """``<IsNull>`` (or ``<IsNotNull>``) element."""
+
+    def __init__(self, field: FieldRef, negate: bool = False) -> None:
+        self.field = field
+        self.negate = negate
+
+    @property
+    def field_refs(self) -> set[str]:
+        return {self.field.name}
+
+    def to_xml(self) -> str:
+        tag = "IsNotNull" if self.negate else "IsNull"
+        return f"<{tag}>{self.field.to_xml()}</{tag}>"
+
+
+class In(CamlExpr):
+    """``<In>`` element over a list of values."""
+
+    def __init__(self, field: FieldRef, values: Iterable[Value]) -> None:
+        self.field = field
+        self.values = list(values)
+
+    @property
+    def field_refs(self) -> set[str]:
+        return {self.field.name}
+
+    def to_xml(self) -> str:
+        values = "".join(value.to_xml() for value in self.values)
+        return f"<In>{self.field.to_xml()}<Values>{values}</Values></In>"
+
+
+class Membership(CamlExpr):
+    """``<Membership>`` element (e.g. ``Type="CurrentUserGroups"``)."""
+
+    def __init__(self, field: FieldRef, type: str = "CurrentUserGroups") -> None:  # noqa: A002
+        self.field = field
+        self.type = type
+
+    @property
+    def field_refs(self) -> set[str]:
+        return {self.field.name}
+
+    def to_xml(self) -> str:
+        from xml.sax.saxutils import quoteattr
+
+        return f"<Membership Type={quoteattr(self.type)}>{self.field.to_xml()}</Membership>"
+
+
+class DateRangesOverlap(CamlExpr):
+    """``<DateRangesOverlap>`` element."""
+
+    def __init__(self, field: FieldRef, value: Value) -> None:
+        self.field = field
+        self.value = value
+
+    @property
+    def field_refs(self) -> set[str]:
+        return {self.field.name}
+
+    def to_xml(self) -> str:
+        return f"<DateRangesOverlap>{self.field.to_xml()}{self.value.to_xml()}</DateRangesOverlap>"
+
+
+class _Binary(CamlExpr):
+    """Base for the binary logical joins (``<And>``/``<Or>``)."""
+
+    tag = ""
+
+    def __init__(self, left: CamlExpr, right: CamlExpr) -> None:
+        self.left = left
+        self.right = right
+
+    @property
+    def field_refs(self) -> set[str]:
+        return self.left.field_refs | self.right.field_refs
+
+    def to_xml(self) -> str:
+        return f"<{self.tag}>{self.left.to_xml()}{self.right.to_xml()}</{self.tag}>"
+
+
+class And(_Binary):
+    """``<And>`` — exactly two children (nest for 3+)."""
+
+    tag = "And"
+
+
+class Or(_Binary):
+    """``<Or>`` — exactly two children (nest for 3+)."""
+
+    tag = "Or"
+
+
+class Not(CamlExpr):
+    """``<Not>`` — exactly one child."""
+
+    def __init__(self, child: CamlExpr) -> None:
+        self.child = child
+
+    @property
+    def field_refs(self) -> set[str]:
+        return self.child.field_refs
+
+    def to_xml(self) -> str:
+        return f"<Not>{self.child.to_xml()}</Not>"
+
+
+def _fold(op: Callable[[CamlExpr, CamlExpr], _T], exprs: Iterable[CamlExpr]) -> _T:
+    """Left-fold conditions into binary-nested nodes (``And(And(A,B),C)``)."""
+    items = list(exprs)
+    if not items:
+        raise ValueError("at least one condition is required")
+    result: Any = items[0]
+    for item in items[1:]:
+        result = op(result, item)
+    return result  # type: ignore[no-any-return]
+
+
+def _as_field_ref(field: Any) -> FieldRef:
+    if isinstance(field, FieldRef):
+        return field
+    if isinstance(field, Field):
+        return field.field_ref
+    return FieldRef(str(field))
+
+
+def _as_value(value: Any, value_type: Optional[ValueType] = None, **value_opts: Any) -> Value:
+    if isinstance(value, Value):
+        return value
+    return Value(value, type=value_type, **value_opts)
+
+
+class Field:
+    """A typed field with fluent comparison methods.
+
+    ``Caml.text("Status").eq("Active")`` renders ``<Eq>`` with ``Type='Text'``;
+    ``Caml.lookup("Category").id().in_([2, 3])`` renders an ``<In>`` over
+    ``Integer`` values with ``LookupId="TRUE"``.
+    """
+
+    def __init__(self, name: str, value_type: ValueType = ValueType.Text, *, lookup_id: bool = False) -> None:
+        self.name = name
+        self.value_type = value_type
+        self.lookup_id = lookup_id
+
+    @property
+    def field_ref(self) -> FieldRef:
+        return FieldRef(self.name, lookup_id=self.lookup_id)
+
+    def id(self) -> "Field":
+        """Treat this field as a lookup id (``LookupId="TRUE"``, ``Integer``)."""
+        return Field(self.name, ValueType.Integer, lookup_id=True)
+
+    def _compare(self, op: str, value: Any, **value_opts: Any) -> Comparison:
+        return Comparison(op, self.field_ref, _as_value(value, self.value_type, **value_opts))
+
+    def eq(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Eq", value, **value_opts)
+
+    def neq(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Neq", value, **value_opts)
+
+    def gt(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Gt", value, **value_opts)
+
+    def geq(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Geq", value, **value_opts)
+
+    def lt(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Lt", value, **value_opts)
+
+    def leq(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Leq", value, **value_opts)
+
+    def begins_with(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("BeginsWith", value, **value_opts)
+
+    def contains(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Contains", value, **value_opts)
+
+    def not_contains(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("NotContains", value, **value_opts)
+
+    def includes(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("Includes", value, **value_opts)
+
+    def not_includes(self, value: Any, **value_opts: Any) -> Comparison:
+        return self._compare("NotIncludes", value, **value_opts)
+
+    def is_null(self) -> IsNull:
+        return IsNull(self.field_ref)
+
+    def is_not_null(self) -> IsNull:
+        return IsNull(self.field_ref, negate=True)
+
+    def in_(self, values: Iterable[Any]) -> In:
+        return In(self.field_ref, [_as_value(value, self.value_type) for value in values])
+
+    def eq_current_user(self) -> Comparison:
+        """``<Eq><FieldRef LookupId='TRUE'/><Value><UserID/></Value></Eq>``."""
+        return Comparison("Eq", self.field_ref, _user_id())
+
+    def in_current_user_groups(self) -> Membership:
+        """``<Membership Type='CurrentUserGroups'>``."""
+        return Membership(self.field_ref, "CurrentUserGroups")
+
+
+class Caml:
+    """Factory namespace for CAML expressions and values."""
+
+    # ── Special values ───────────────────────────────────────────
+    now: Value = _now()
+    today: Value = _today()
+    month: Value = _month()
+    user_id: Value = _user_id()
+    list_property = staticmethod(list_property)
+
+    # ── Typed fields ─────────────────────────────────────────────
+    @staticmethod
+    def field(name: str, value_type: ValueType = ValueType.Text, *, lookup_id: bool = False) -> Field:
+        return Field(name, value_type, lookup_id=lookup_id)
+
+    @staticmethod
+    def text(name: str) -> Field:
+        return Field(name, ValueType.Text)
+
+    @staticmethod
+    def number(name: str) -> Field:
+        return Field(name, ValueType.Number)
+
+    @staticmethod
+    def integer(name: str) -> Field:
+        return Field(name, ValueType.Integer)
+
+    @staticmethod
+    def date(name: str) -> Field:
+        return Field(name, ValueType.DateTime)
+
+    @staticmethod
+    def boolean(name: str) -> Field:
+        return Field(name, ValueType.Boolean)
+
+    @staticmethod
+    def lookup(name: str, *, id: bool = False) -> Field:  # noqa: A002
+        return Field(name, ValueType.Integer, lookup_id=id)
+
+    @staticmethod
+    def user(name: str) -> Field:
+        return Field(name, ValueType.Integer, lookup_id=True)
+
+    # ── Comparisons (by field name, Field or FieldRef) ───────────
+    @staticmethod
+    def _compare(op: str, field: Any, value: Any, value_type: Optional[ValueType] = None) -> Comparison:
+        return Comparison(op, _as_field_ref(field), _as_value(value, value_type))
+
+    @staticmethod
+    def eq(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Eq", field, value)
+
+    @staticmethod
+    def neq(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Neq", field, value)
+
+    @staticmethod
+    def gt(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Gt", field, value)
+
+    @staticmethod
+    def geq(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Geq", field, value)
+
+    @staticmethod
+    def lt(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Lt", field, value)
+
+    @staticmethod
+    def leq(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Leq", field, value)
+
+    @staticmethod
+    def begins_with(field: Any, value: Any) -> Comparison:
+        return Caml._compare("BeginsWith", field, value)
+
+    @staticmethod
+    def contains(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Contains", field, value)
+
+    @staticmethod
+    def not_contains(field: Any, value: Any) -> Comparison:
+        return Caml._compare("NotContains", field, value)
+
+    @staticmethod
+    def includes(field: Any, value: Any) -> Comparison:
+        return Caml._compare("Includes", field, value)
+
+    @staticmethod
+    def not_includes(field: Any, value: Any) -> Comparison:
+        return Caml._compare("NotIncludes", field, value)
+
+    @staticmethod
+    def is_null(field: Any) -> IsNull:
+        return IsNull(_as_field_ref(field))
+
+    @staticmethod
+    def is_not_null(field: Any) -> IsNull:
+        return IsNull(_as_field_ref(field), negate=True)
+
+    @staticmethod
+    def in_(field: Any, values: Iterable[Any], value_type: Optional[ValueType] = None) -> In:
+        return In(_as_field_ref(field), [_as_value(value, value_type) for value in values])
+
+    @staticmethod
+    def membership(field: Any, type: str = "CurrentUserGroups") -> Membership:  # noqa: A002
+        return Membership(_as_field_ref(field), type)
+
+    @staticmethod
+    def date_ranges_overlap(field: Any, value: Any) -> DateRangesOverlap:
+        return DateRangesOverlap(_as_field_ref(field), _as_value(value))
+
+    # ── Logical joins ────────────────────────────────────────────
+    @staticmethod
+    def and_(*exprs: CamlExpr) -> CamlExpr:
+        return _fold(And, exprs)
+
+    @staticmethod
+    def or_(*exprs: CamlExpr) -> CamlExpr:
+        return _fold(Or, exprs)
+
+    @staticmethod
+    def not_(expr: CamlExpr) -> Not:
+        return Not(expr)

office365/sharepoint/listitems/caml/fields.py

@@ -0,0 +1,68 @@
+"""Typed CAML ``<FieldRef>`` nodes."""
+
+from __future__ import annotations
+
+from typing import Optional
+from xml.sax.saxutils import quoteattr
+
+
+class FieldRef:
+    """A CAML ``<FieldRef>`` element.
+
+    ``Ascending``/``Collapse`` apply inside ``<OrderBy>``/``<GroupBy>``;
+    ``LookupId``/``RefType``/``List`` support lookup and join clauses.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        ascending: Optional[bool] = None,
+        collapse: Optional[bool] = None,
+        nullable: Optional[bool] = None,
+        lookup_id: bool = False,
+        ref_type: Optional[str] = None,
+        list_alias: Optional[str] = None,
+    ) -> None:
+        self.name = name
+        self.ascending = ascending
+        self.collapse = collapse
+        self.nullable = nullable
+        self.lookup_id = lookup_id
+        self.ref_type = ref_type
+        self.list_alias = list_alias
+
+    def asc(self) -> "FieldRef":
+        """A copy sorted ascending (for ``<OrderBy>``)."""
+        return self._copy(ascending=True)
+
+    def desc(self) -> "FieldRef":
+        """A copy sorted descending (for ``<OrderBy>``)."""
+        return self._copy(ascending=False)
+
+    def _copy(self, **overrides) -> "FieldRef":
+        return FieldRef(
+            self.name,
+            ascending=overrides.get("ascending", self.ascending),
+            collapse=overrides.get("collapse", self.collapse),
+            nullable=overrides.get("nullable", self.nullable),
+            lookup_id=self.lookup_id,
+            ref_type=self.ref_type,
+            list_alias=self.list_alias,
+        )
+
+    def to_xml(self) -> str:
+        attrs = [f"Name={quoteattr(self.name)}"]
+        if self.ascending is not None:
+            attrs.append(f'Ascending="{str(self.ascending).upper()}"')
+        if self.collapse is not None:
+            attrs.append(f'Collapse="{str(self.collapse).upper()}"')
+        if self.nullable is not None:
+            attrs.append(f'Nullable="{str(self.nullable).upper()}"')
+        if self.lookup_id:
+            attrs.append('LookupId="TRUE"')
+        if self.ref_type is not None:
+            attrs.append(f"RefType={quoteattr(self.ref_type)}")
+        if self.list_alias is not None:
+            attrs.append(f"List={quoteattr(self.list_alias)}")
+        return f"<FieldRef {' '.join(attrs)}/>"

office365/sharepoint/listitems/caml/guard.py

@@ -0,0 +1,63 @@
+"""CAML guards for the SharePoint **list view threshold**.
+
+CAML parsing lives on :class:`~office365.sharepoint.listitems.caml.query.CamlQuery`
+(``is_paged``/``field_refs``); this module owns the policy that turns it into
+warnings and the columns worth indexing. It is a plain function API (not a
+decorator), so it stays explicit and easy to test in isolation.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Optional
+
+from office365.sharepoint.listitems.caml.query import CamlQuery
+from office365.sharepoint.thresholds import LIST_VIEW_THRESHOLD, SAFE_PAGE_SIZE
+
+
+def indexing_candidates(query: CamlQuery) -> set[str]:
+    """Field names referenced by the query that are worth indexing (``ID`` excluded)."""
+    return set(query.index_candidates)
+
+
+def threshold_warnings(
+    query: CamlQuery,
+    *,
+    item_count: Optional[int] = None,
+    threshold: int = LIST_VIEW_THRESHOLD,
+) -> list[str]:
+    """Warnings for a CAML query that may exceed the list view threshold.
+
+    Empty when the query is paged, when the list is known to be at/below the
+    threshold, or when an unpaged query references no columns (a plain
+    ``create_all_items_query`` on a list whose size is unknown).
+    """
+    if query.is_paged:
+        return []
+    if item_count is not None and item_count <= threshold:
+        return []
+    names = sorted(indexing_candidates(query))
+    if not names and item_count is None:
+        return []
+    fields = f" on column(s) {', '.join(repr(name) for name in names)}" if names else ""
+    hint = (
+        f"index them with ensure_indexed(...) (e.g. lst.ensure_indexed({names[0]!r}).execute_query())"
+        if names
+        else "index the filtered/sorted columns with ensure_indexed(...)"
+    )
+    return [
+        f"This CAML query is not paged and may exceed the SharePoint list view threshold "
+        f"({threshold:,} items){fields}. Pass page_size={SAFE_PAGE_SIZE} to get_items(), add "
+        f"RowLimit Paged='TRUE' and iterate, or {hint} to avoid throttling."
+    ]
+
+
+def warn_if_unpaged(
+    query: CamlQuery,
+    *,
+    item_count: Optional[int] = None,
+    threshold: int = LIST_VIEW_THRESHOLD,
+) -> None:
+    """Emit a :class:`UserWarning` per issue from :func:`threshold_warnings`."""
+    for message in threshold_warnings(query, item_count=item_count, threshold=threshold):
+        warnings.warn(message, stacklevel=3)