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

office365/sharepoint/listitems/caml/values.py

@@ -0,0 +1,113 @@
+"""Typed CAML ``<Value>`` nodes.
+
+A :class:`Value` renders a ``<Value Type='...'>...</Value>`` element, inferring
+the OData value type from the Python value (``str`` -> ``Text``, ``int`` ->
+``Integer``, ``bool`` -> ``Boolean``, ``datetime`` -> ``DateTime``) unless an
+explicit type is given. Special values (``Now``/``Today``/``Month``/``UserID``/
+``ListProperty``) render a child element instead of literal text.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Optional
+from xml.sax.saxutils import escape, quoteattr
+
+
+class ValueType(str, Enum):
+    """The ``Type`` attribute of a CAML ``<Value>`` element."""
+
+    Text = "Text"
+    Note = "Note"
+    Integer = "Integer"
+    Counter = "Counter"
+    Number = "Number"
+    Currency = "Currency"
+    DateTime = "DateTime"
+    Boolean = "Boolean"
+    Lookup = "Lookup"
+    User = "User"
+    Choice = "Choice"
+    URL = "URL"
+    Guid = "Guid"
+    Calculated = "Calculated"
+
+
+def infer_value_type(value: Any) -> ValueType:
+    """Infer the CAML ``ValueType`` from a Python value."""
+    if isinstance(value, bool):  # bool before int (bool is an int subclass)
+        return ValueType.Boolean
+    if isinstance(value, int):
+        return ValueType.Integer
+    if isinstance(value, float):
+        return ValueType.Number
+    if isinstance(value, (datetime, date)):
+        return ValueType.DateTime
+    return ValueType.Text
+
+
+class Value:
+    """A CAML ``<Value>`` element."""
+
+    def __init__(
+        self,
+        value: Any = None,
+        *,
+        type: Optional[ValueType | str] = None,  # noqa: A002
+        include_time_value: bool = False,
+        lookup_id: bool = False,
+        child: Optional[str] = None,
+    ) -> None:
+        self._value = value
+        self._type = ValueType(type) if isinstance(type, str) else type
+        self._include_time_value = include_time_value
+        self._lookup_id = lookup_id
+        self._child = child  # raw child XML (e.g. "<Now/>")
+
+    @property
+    def value_type(self) -> ValueType:
+        """The resolved ``ValueType`` (explicit type, else inferred)."""
+        return self._type or infer_value_type(self._value)
+
+    def to_xml(self) -> str:
+        attrs = [f"Type={quoteattr(self.value_type.value)}"]
+        if self._include_time_value:
+            attrs.append('IncludeTimeValue="TRUE"')
+        if self._lookup_id:
+            attrs.append('LookupId="TRUE"')
+        inner = self._child if self._child is not None else escape(self._format(self._value))
+        return f"<Value {' '.join(attrs)}>{inner}</Value>"
+
+    @staticmethod
+    def _format(value: Any) -> str:
+        if isinstance(value, bool):
+            return "1" if value else "0"
+        if isinstance(value, (datetime, date)):
+            return value.isoformat()
+        return str(value)
+
+
+def now() -> Value:
+    """A ``<Value Type='DateTime'><Now/></Value>`` node."""
+    return Value(type=ValueType.DateTime, child="<Now/>")
+
+
+def today() -> Value:
+    """A ``<Value Type='DateTime'><Today/></Value>`` node."""
+    return Value(type=ValueType.DateTime, child="<Today/>")
+
+
+def month() -> Value:
+    """A ``<Value Type='Integer'><Month/></Value>`` node."""
+    return Value(type=ValueType.Integer, child="<Month/>")
+
+
+def user_id() -> Value:
+    """A ``<Value Type='Integer'><UserID/></Value>`` node."""
+    return Value(type=ValueType.Integer, child="<UserID/>")
+
+
+def list_property(name: str) -> Value:
+    """A ``<Value><ListProperty Name='...'/></Value>`` node."""
+    return Value(child=f"<ListProperty Name={quoteattr(name)}/>")

office365/sharepoint/listitems/collection.py

@@ -7,51 +7,52 @@ from typing_extensions import Self
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.listitems.listitem import ListItem
+from office365.sharepoint.thresholds import LIST_VIEW_THRESHOLD
 
 if TYPE_CHECKING:
+    from office365.runtime.converters.upsert import UpsertTarget
     from office365.runtime.operations import ProgressCallback
 
 
 class ListItemCollection(EntityCollection[ListItem]):
     """List Item collection"""
 
-    def __init__(self, context, resource_path=None):
-        super().__init__(context, ListItem, resource_path)
+    _list_view_threshold = LIST_VIEW_THRESHOLD
+    _truncation_hint = "page it with List.get_items(query, page_size=2000) or items.get_all(page_size=2000)"
 
-    def from_records(self, records, progress: "ProgressCallback | None" = None) -> Self:
+    def __init__(self, context, resource_path=None, parent=None):
+        super().__init__(context, ListItem, resource_path, parent)
+
+    def queue_records(self, records, progress: "ProgressCallback | None" = None) -> Self:
         """Queue an item create per record.
 
         List item columns are defined per list at runtime, not on the ``ListItem``
         class, so every record key is forwarded to the server (no unknown-column
         filtering). Deferred — run the creates with ``execute_query()``.
-
-        Args:
-            records: Plain dict records to import.
-            progress: Optional hook invoked per queued create as it completes
-              during ``execute_query()``.
-
-        Returns:
-            Self: The item collection, for method chaining.
         """
         from office365.runtime.converters.csv_reader import coerce_records
 
         return self._import_records(coerce_records(self._item_type, records, allow_unknown=True), progress=progress)
 
-    def get_by_id(self, item_id: int) -> ListItem:
-        """Returns the list item with the specified list item identifier.
+    def upsert_target(self, *, key_field: str = "MigrationKey", enforce_unique: bool = False) -> "UpsertTarget":
+        """The keyed skip/upsert target for this list (see ``from_records(key=...)``)."""
+        from office365.sharepoint.listitems.upsert import ListItemUpsertTarget
 
-        Args:
-            item_id (int): The list item identifier.
-        """
+        return ListItemUpsertTarget(self, key_field=key_field, enforce_unique=enforce_unique)
+
+    def _key_column(self, column: str) -> str:
+        """List-item record keys are field internal names (``Name`` -> ``Name_``)."""
+        from office365.sharepoint.fields.name import internal_field_name
+
+        return internal_field_name(column)
+
+    def get_by_id(self, item_id: int) -> ListItem:
+        """Returns the list item with the specified list item identifier."""
         return ListItem(self.context, ServiceOperationPath("GetById", [item_id], self.resource_path))
 
     def get_by_string_id(self, s_id: str) -> ListItem:
         """Returns the list item with either the specified list item identifier or the specified identifier
         for an instance of an external content type.
-
-        Args:
-            s_id (str): Specifies the list item identifier, or if the list is an external list, specifies the identifier
-                for an instance of an external content type as specified in[MS-ECTPWPS] section 3.1.4.1.2.1.
         """
         return ListItem(
             self.context,

office365/sharepoint/listitems/upsert.py

@@ -0,0 +1,75 @@
+"""SharePoint list-item :class:`UpsertTarget` — the destination side of keyed imports.
+
+Keeps the SharePoint-specific pieces (ensure the key column, load existing keys,
+create/update items) out of the runtime upsert core, so the same
+:func:`~office365.runtime.converters.upsert.keyed_queue` drives list imports and
+the migration toolkit.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping, cast
+
+from office365.runtime.paths.v3.entity import EntityPath
+from office365.sharepoint.fields.type import FieldType
+from office365.sharepoint.listitems.listitem import ListItem
+
+if TYPE_CHECKING:
+    from office365.sharepoint.listitems.collection import ListItemCollection
+    from office365.sharepoint.lists.list import List
+
+
+class ListItemUpsertTarget:
+    """Keyed skip/upsert target backed by a :class:`ListItemCollection`."""
+
+    def __init__(
+        self,
+        collection: "ListItemCollection",
+        *,
+        key_field: str = "MigrationKey",
+        enforce_unique: bool = False,
+    ) -> None:
+        self._collection = collection
+        self._key_field = key_field
+        self._enforce_unique = enforce_unique
+
+    @property
+    def key_field(self) -> str:
+        return self._key_field
+
+    def ensure_key_field(self) -> None:
+        """Queue the key column (Text, optionally unique+indexed) if missing."""
+        from office365.sharepoint.fields.creation_information import FieldCreationInformation
+
+        parent = cast("List", self._collection.parent)
+        if parent is None:
+            return
+        field = parent.fields.ensure(FieldCreationInformation(Title=self._key_field, FieldTypeKind=FieldType.Text))
+        if self._enforce_unique:
+            field.set_property("EnforceUniqueValues", True)
+            field.set_property("Indexed", True)
+            field.update()
+
+    def load_keys(self) -> Mapping[str, Any]:
+        """Return the existing ``{key: item_id}`` map (paged; key + ``Id`` only)."""
+        loaded = self._collection.select([self._key_field, "Id"]).get_all().execute_query()
+        keys: dict[str, Any] = {}
+        for item in loaded:
+            value = item.properties.get(self._key_field)
+            item_id = item.id
+            if value is not None and item_id is not None:
+                keys[str(value)] = item_id
+        return keys
+
+    def create_records(self, records: list[dict]) -> None:
+        self._collection.queue_records(records)
+
+    def update_record(self, item_id: Any, record: dict) -> None:
+        item = ListItem(
+            self._collection.context,
+            EntityPath(item_id, self._collection.resource_path),
+            parent_list=self._collection.parent,
+        )
+        for name, value in record.items():
+            item.set_property(name, value, persist_changes=True)
+        item.update()

office365/sharepoint/lists/collection.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Optional
 
-from office365.runtime.client_request_exception import ClientRequestException, DuplicatedObjectException
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.paths.v3.entity import EntityPath
@@ -73,39 +72,47 @@ class ListCollection(EntityCollection[List]):
         )
 
     def ensure_list(
-        self, title: str, description: str | None = None, template_type: ListTemplateType = ListTemplateType.GenericList
+        self,
+        title: str,
+        description: str | None = None,
+        template_type: ListTemplateType = ListTemplateType.GenericList,
+        allow_content_types: bool = False,
+        *,
+        on_conflict: str = "skip",
     ) -> List:
         """Gets the list with the given title, or creates it if it does not exist.
 
-        Attempts to create the list via ``add_list``; if the server reports that
-        a list with the title already exists (``DuplicatedObjectException``), the
-        existing list is loaded instead and its properties are copied into the
-        returned object. All other errors propagate.
-
-        The result is deferred: resolve it with ``execute_query()`` before use,
-        e.g.::
-
-            >>> lst = ctx.web.lists.ensure_list("My List").execute_query()
+        Idempotent (deferred — resolve with ``execute_query()``). With
+        ``on_conflict="update"`` the existing list's description is reconciled.
 
         Args:
             title: Title of the list to get or create
             description: Description of the list to get or create
             template_type: Type of list to get or create
+            allow_content_types: Whether to enable content types
+            on_conflict: ``"skip"`` (default) or ``"update"``.
 
         Returns:
             List: The existing or newly created list
         """
-        return_type = self.add_list(title=title, description=description, template_type=template_type)
-
-        def _on_name_exists(error: ClientRequestException):
-            if not isinstance(error, DuplicatedObjectException):
-                raise error
-            self.get_by_title(title).get().after_execute(
-                lambda existing: return_type.copy_from(existing), execute_first=True
-            )
-
-        return_type.on_error(_on_name_exists)
-        return return_type
+        from office365.runtime.queries.get_or_create import create_or_get
+
+        def _reconcile(lst: List) -> None:
+            if description is not None and lst.properties.get("Description") != description:
+                lst.set_property("Description", description)
+                lst.update()
+
+        return create_or_get(
+            create=lambda: self.add_list(
+                title=title,
+                description=description,
+                template_type=template_type,
+                allow_content_types=allow_content_types,
+            ),
+            find=lambda: self.get_by_title(title).get(),
+            on_conflict=on_conflict,
+            reconcile=_reconcile,
+        )
 
     def ensure_client_rendered_site_pages_library(self) -> List:
         """

office365/sharepoint/lists/exporter.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from typing import IO, TYPE_CHECKING, Callable, Optional, Union
 
 from office365.runtime.client_result import ClientResult
+from office365.sharepoint.fields.builtin_field_name import SPBuiltInFieldName
 from office365.sharepoint.files.system_object_type import FileSystemObjectType
 from office365.sharepoint.listitems.collection import ListItemCollection
 from office365.sharepoint.listitems.listitem import ListItem
@@ -72,9 +73,9 @@ class ListExporter:
                     [
                         "*",
                         "Id",
-                        "FileRef",
-                        "FileDirRef",
-                        "FileLeafRef",
+                        SPBuiltInFieldName.FileRef,
+                        SPBuiltInFieldName.FileDirRef,
+                        SPBuiltInFieldName.FileLeafRef,
                         "FileSystemObjectType",
                     ]
                 )