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

office365/sharepoint/fields/coercion.py

@@ -0,0 +1,131 @@
+"""Typed field value coercion for record imports.
+
+Maps plain source values (CSV/DataFrame cells) to the payload shapes SharePoint
+expects for typed fields, driven by an explicit ``schema={column: FieldType}``.
+``List.from_records(..., schema=...)`` (and the streaming conveniences) applies
+this, so typed columns (choice, lookup, user, URL, geolocation, ...) can be
+populated without hand-building payloads:
+
+    lst.from_dataframe(df, schema={"Status": FieldType.Choice, "Tags": FieldType.MultiChoice})
+
+Values already in the expected shape (a ``ClientValue``) pass through unchanged.
+``None`` values and unknown/``None`` field types are left as-is, so this is safe
+to apply to every cell of a record.
+
+SharePoint has no distinct field-type kind for multi-valued lookups/users (they
+are ``Lookup``/``User`` fields with ``AllowMultipleValues``), so the value's
+shape decides: a list, tuple or ``"; "``-separated string becomes the multi form.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, Callable, Dict, Optional
+
+from office365.runtime.client_value import ClientValue
+from office365.runtime.converters.scalars import parse_bool, parse_datetime, try_float, try_int
+from office365.sharepoint.fields.geolocation_value import FieldGeolocationValue
+from office365.sharepoint.fields.lookup_value import FieldLookupValue
+from office365.sharepoint.fields.multi_choice_value import FieldMultiChoiceValue
+from office365.sharepoint.fields.multi_lookup_value import FieldMultiLookupValue
+from office365.sharepoint.fields.multi_user_value import FieldMultiUserValue
+from office365.sharepoint.fields.type import FieldType
+from office365.sharepoint.fields.url_value import FieldUrlValue
+from office365.sharepoint.fields.user_value import FieldUserValue
+
+_LIST_SEPARATOR = ";"
+
+
+def _as_list(value: Any) -> list[Any]:
+    """Normalize a value into a list (a ``"; "`` string is split)."""
+    if isinstance(value, str):
+        return [part.strip() for part in value.split(_LIST_SEPARATOR) if part.strip()]
+    if isinstance(value, Iterable):
+        return list(value)
+    return [value]
+
+
+def _is_multi(value: Any) -> bool:
+    """Whether a value should map to a multi-valued field."""
+    return isinstance(value, (list, tuple)) or (isinstance(value, str) and _LIST_SEPARATOR in value)
+
+
+def _lookup_id(value: Any) -> int:
+    """Read a lookup id from a mapping (``LookupId``/``Id``) or a scalar."""
+    if isinstance(value, Mapping):
+        value = value.get("LookupId", value.get("Id", value.get("id")))
+    return int(value)
+
+
+def _lookup_value(value: Any) -> Any:
+    if _is_multi(value):
+        return FieldMultiLookupValue([FieldLookupValue(LookupId=_lookup_id(item)) for item in _as_list(value)])
+    return FieldLookupValue(LookupId=_lookup_id(value))
+
+
+def _user_value(value: Any) -> FieldUserValue:
+    if isinstance(value, Mapping):
+        has_id = value.get("LookupId") is not None or value.get("Id") is not None
+        return FieldUserValue(
+            LookupId=_lookup_id(value) if has_id else None,
+            LookupValue=value.get("LookupValue"),
+            Email=value.get("Email", value.get("email")),
+        )
+    if isinstance(value, str) and "@" in value:
+        return FieldUserValue(Email=value)
+    return FieldUserValue(LookupId=_lookup_id(value))
+
+
+def _user(value: Any) -> Any:
+    if _is_multi(value):
+        return FieldMultiUserValue([_user_value(item) for item in _as_list(value)])
+    return _user_value(value)
+
+
+def _url(value: Any) -> FieldUrlValue:
+    if isinstance(value, Mapping):
+        return FieldUrlValue(Url=value.get("Url"), Description=value.get("Description"))
+    if isinstance(value, (tuple, list)):
+        return FieldUrlValue(Url=value[0], Description=value[1] if len(value) > 1 else None)
+    return FieldUrlValue(Url=str(value))
+
+
+def _geolocation(value: Any) -> FieldGeolocationValue:
+    if isinstance(value, Mapping):
+        return FieldGeolocationValue(Latitude=float(value["Latitude"]), Longitude=float(value["Longitude"]))
+    if isinstance(value, (tuple, list)) and len(value) > 1:
+        return FieldGeolocationValue(Latitude=float(value[0]), Longitude=float(value[1]))
+    latitude, _, longitude = str(value).partition(",")
+    return FieldGeolocationValue(Latitude=float(latitude), Longitude=float(longitude))
+
+
+def _datetime(value: Any) -> Any:
+    return parse_datetime(value) or value
+
+
+_CONVERTERS: Dict[FieldType, Callable[[Any], Any]] = {
+    FieldType.Boolean: parse_bool,
+    FieldType.Integer: try_int,
+    FieldType.Counter: try_int,
+    FieldType.Number: try_float,
+    FieldType.Currency: try_float,
+    FieldType.DateTime: _datetime,
+    FieldType.MultiChoice: lambda value: FieldMultiChoiceValue([str(item) for item in _as_list(value)]),
+    FieldType.Lookup: _lookup_value,
+    FieldType.User: _user,
+    FieldType.URL: _url,
+    FieldType.Geolocation: _geolocation,
+}
+
+
+def coerce_field_value(field_type: Optional[FieldType], value: Any) -> Any:
+    """Coerce a plain value into the payload shape for ``field_type``.
+
+    Supported: Boolean, Integer, Number/Currency, DateTime, MultiChoice, Lookup
+    (single/multi), User (single/multi), URL and Geolocation. Anything else (and
+    already-typed ``ClientValue`` inputs) passes through unchanged.
+    """
+    if field_type is None or value is None or isinstance(value, ClientValue):
+        return value
+    converter = _CONVERTERS.get(field_type)
+    return converter(value) if converter is not None else value

office365/sharepoint/fields/collection.py

@@ -2,12 +2,6 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, cast
 
-from typing_extensions import Self
-
-from office365.runtime.client_request_exception import (
-    ClientRequestException,
-    ObjectNotFoundException,
-)
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.create_entity import CreateEntityQuery
 from office365.runtime.queries.service_operation import ServiceOperationQuery
@@ -42,8 +36,14 @@ _FIELD_TYPE_BY_KIND = {
 
 
 def field_type_from_kind(kind: str) -> FieldType:
-    """Map a generic pandas dtype kind (see ``series_kind``) to a SharePoint ``FieldType``."""
-    return _FIELD_TYPE_BY_KIND[kind]
+    """Map a generic pandas dtype kind (see ``series_kind``) to a SharePoint ``FieldType``.
+
+    Unknown kinds fall back to ``FieldType.Text``. Only the four basic column
+    types can be inferred from a pandas dtype; richer SharePoint types (Choice,
+    Lookup, User, URL, Currency, MultiLineText, ...) require an explicit
+    ``schema`` passed to ``List.from_dataframe``.
+    """
+    return _FIELD_TYPE_BY_KIND.get(kind, FieldType.Text)
 
 
 if TYPE_CHECKING:
@@ -57,59 +57,76 @@ class FieldCollection(EntityCollection[Field]):
     def __init__(self, context, resource_path=None, parent=None):
         super().__init__(context, Field, resource_path, parent)
 
-    def from_dataframe(self, df, progress=None) -> Self:
+    def ensure_from_dataframe(self, df, progress=None, *, on_conflict: str = "skip") -> list[Field]:
         """Define a field per DataFrame column, inferring the field type.
 
-        The schema counterpart of ``ClientObjectCollection.from_dataframe``
-        (which imports rows): here each column becomes a field definition.
-        Column names are sanitized into field internal names and the
-        ``FieldType`` is inferred from the pandas dtype (Boolean/DateTime/
-        Number/Text). Each field is ensured idempotently (looked up first,
-        created when missing). Deferred — run the lookups/creates with
-        ``execute_query()``:
+        The schema counterpart of ``RecordCollection.from_dataframe`` (which
+        imports rows): here each column becomes a field definition. Column names
+        are sanitized into field internal names and the ``FieldType`` is inferred
+        from the pandas dtype (Boolean/DateTime/Number/Text). Each field is
+        ensured idempotently (looked up first, created when missing). Deferred —
+        run the lookups/creates with ``execute_query()``.
 
-            >>> lst.fields.from_dataframe(df).execute_query()
+        A column whose title collides with a built-in field (e.g. ``Name`` ->
+        ``FileLeafRef``) is suffixed with ``_`` and a warning is emitted, since
+        SharePoint cannot create a second column with that display name.
 
         Requires ``pip install office365-rest-python-client[pandas]``.
 
         Args:
             df: A pandas DataFrame whose columns become the field definitions.
+            progress: Reserved (kept for signature parity).
+            on_conflict: ``"skip"`` (default) or ``"update"``.
 
         Returns:
-            Self: The field collection, for method chaining.
+            list[Field]: The ensured fields.
         """
+        import warnings
+
         from office365.runtime.converters.dataframe import require_pandas, series_kind
-        from office365.sharepoint.fields.name import internal_field_name
+        from office365.sharepoint.fields.name import internal_field_name, is_reserved_field_title
 
         pd = require_pandas()
+        fields: list[Field] = []
         for column in df.columns:
+            if is_reserved_field_title(str(column)):
+                warnings.warn(
+                    f"Column '{column}' collides with a built-in SharePoint field; "
+                    f"importing it as '{internal_field_name(str(column))}'.",
+                    stacklevel=2,
+                )
             field_type = field_type_from_kind(series_kind(pd, df[column]))
             info = FieldCreationInformation(
                 Title=internal_field_name(str(column)),
                 FieldTypeKind=field_type,
             )
-            self.ensure(info)
-        return self
+            fields.append(self.ensure(info, on_conflict=on_conflict))
+        return fields
 
-    def ensure(self, parameters: FieldCreationInformation) -> Field:
-        from office365.runtime.queries.deferred import DeferredOperationQuery
+    def ensure(self, parameters: FieldCreationInformation, *, on_conflict: str = "skip") -> Field:
+        """Ensure the field exists (get-or-create); ``on_conflict="update"`` reconciles it."""
+        from office365.runtime.queries.get_or_create import get_or_create
 
         return_type = Field(self.context)
-        barrier = DeferredOperationQuery(self.context, return_type=return_type)
-
-        def _on_success(existing):
-            return_type.copy_from(existing)
-            barrier.resolve()
 
-        def _on_error(error: ClientRequestException):
-            if not isinstance(error, ObjectNotFoundException):
-                raise error
-
-            barrier.defer(self._build_add_field_query(parameters, return_type))
-
-        self.get_by_title(parameters.Title).get().after_execute(_on_success).on_error(_on_error)
-        self.context.add_query(barrier)
-        return return_type
+        def _reconcile(field: Field) -> None:
+            changed = False
+            if parameters.FieldTypeKind is not None and field.field_type_kind != parameters.FieldTypeKind:
+                field.set_property("FieldTypeKind", parameters.FieldTypeKind)
+                changed = True
+            if parameters.Description is not None and field.properties.get("Description") != parameters.Description:
+                field.set_property("Description", parameters.Description)
+                changed = True
+            if changed:
+                field.update()
+
+        return get_or_create(
+            find=lambda: self.get_by_title(parameters.Title).get(),
+            create_query=lambda: self._build_add_field_query(parameters, return_type),
+            return_type=return_type,
+            on_conflict=on_conflict,
+            reconcile=_reconcile,
+        )
 
     def add_calculated(self, title: str, formula: str, description: Optional[str] = None) -> FieldCalculated:
         """Creates a Calculated field

office365/sharepoint/fields/field.py

@@ -279,6 +279,23 @@ class Field(Entity):
     def indexed(self):
         return self.properties.get("Indexed", None)
 
+    def ensure_indexed(self) -> Self:
+        """Ensure this field is indexed (idempotent, deferred).
+
+        Indexing a column lets queries filter/sort on it past the 5,000-item list
+        view threshold. Run with ``execute_query()``.
+        """
+
+        def _enable(_=None) -> None:
+            if self.indexed is not True:
+                self.enable_index()
+
+        if self.indexed is None:
+            self.ensure_property("Indexed").after_execute(_enable)
+        else:
+            _enable()
+        return self
+
     @property
     def type_display_name(self) -> Optional[str]:
         """

office365/sharepoint/fields/name.py

@@ -2,10 +2,54 @@ from __future__ import annotations
 
 import re
 
+# Built-in SharePoint field titles that collide with a user column of the same
+# name. ``FieldCollection.ensure`` looks fields up by *display name*
+# (``getByTitle``), so a column titled e.g. "Name" resolves to the built-in
+# ``FileLeafRef`` field and is never created as a custom column. Such titles are
+# suffixed with ``_`` so the column can be imported (and the item keys stay
+# consistent, since both field creation and record keys use this mapping).
+_RESERVED_FIELD_TITLES = frozenset(
+    {
+        "name",  # FileLeafRef
+        "title",
+        "id",
+        "created",
+        "modified",
+        "author",
+        "editor",
+        "attachments",
+        "contenttype",
+        "contenttypeid",
+        "version",
+        "uniqueid",
+        "fileleafref",
+        "fileref",
+        "filedirref",
+        "fsobjtype",
+        "owshiddenversion",
+        "workflowversion",
+        "metainfo",
+        "scopeid",
+        "instanceid",
+        "permask",
+    }
+)
+
 
 def internal_field_name(name: str) -> str:
     """Sanitize a display/column name into a SharePoint field internal name.
 
-    SharePoint field internal names cannot contain spaces or punctuation.
+    SharePoint field internal names cannot contain spaces or punctuation, and a
+    title that collides with a built-in field's display name (e.g. ``Name`` ->
+    ``FileLeafRef``) cannot be created as a custom column — those are suffixed
+    with ``_`` so the import still works.
     """
-    return re.sub(r"\W", "_", name)
+    sanitized = re.sub(r"\W", "_", name)
+    if sanitized.lower() in _RESERVED_FIELD_TITLES:
+        return f"{sanitized}_"
+    return sanitized
+
+
+def is_reserved_field_title(name: str) -> bool:
+    """Whether a column title collides with a built-in SharePoint field title."""
+    return re.sub(r"\W", "_", name).lower() in _RESERVED_FIELD_TITLES

office365/sharepoint/files/collection.py

@@ -17,12 +17,13 @@ from office365.sharepoint.files.creation_information import FileCreationInformat
 from office365.sharepoint.files.file import File
 from office365.sharepoint.files.publish.status import FileStatus
 from office365.sharepoint.pages.template_file_type import TemplateFileType
+from office365.sharepoint.thresholds import LIST_VIEW_THRESHOLD, Limits, ensure_within, limit
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 if TYPE_CHECKING:
     from office365.sharepoint.folders.folder import Folder
 
-_DEFAULT_CHUNK_SIZE = 4 * 1024 * 1024  # simple-upload threshold / upload-session chunk
+_DEFAULT_CHUNK_SIZE = Limits.UPLOAD_SESSION_CHUNK.value  # simple-upload threshold / upload-session chunk
 
 
 def _stream_size(stream: IO) -> int:
@@ -47,6 +48,9 @@ def _stream_size(stream: IO) -> int:
 class FileCollection(EntityCollection[File]):
     """Represents a collection of File resources."""
 
+    _list_view_threshold = LIST_VIEW_THRESHOLD
+    _truncation_hint = "page it with Folder.get_files(page_size=2000) or files.get_all(page_size=2000)"
+
     def __init__(
         self,
         context: ClientContext,
@@ -82,6 +86,7 @@ class FileCollection(EntityCollection[File]):
             content = path_or_file.read()
             return self.add(name, content, True)
 
+    @limit(Limits.FILE_UPLOAD)
     def upload_content(
         self,
         content: bytes,
@@ -103,6 +108,7 @@ class FileCollection(EntityCollection[File]):
               (``done``/``total`` in bytes; per chunk for session uploads, once
               after the upload completes for the simple path).
         """
+        ensure_within(Limits.FILE_UPLOAD, len(content), context=f"file '{file_name}'")
         if len(content) <= chunk_size:
             file = self.upload(io.BytesIO(content), file_name)
             if callable(progress):

office365/sharepoint/files/file.py

@@ -49,6 +49,7 @@ from office365.sharepoint.webparts.limited_manager import LimitedWebPartManager
 from office365.sharepoint.webparts.personalization_scope import PersonalizationScope
 
 if TYPE_CHECKING:
+    from office365.runtime.converters.dataframe import DataFrameResult
     from office365.sharepoint.client_context import ClientContext
 
 
@@ -145,6 +146,37 @@ class File(AbstractFile):
         self.context.add_query(qry)
         return return_type
 
+    def read_dataframe(self, *, format: str = "csv", **opts) -> "DataFrameResult":  # noqa: A002
+        """Read this file's **content** into a pandas DataFrame (deferred result).
+
+        Parses the file content (CSV/XLSX/JSON/Parquet) — it does **not** export
+        the file's metadata; those are plain properties (``file.name``,
+        ``file.length``, ``file.time_last_modified``, ...). Run with
+        ``execute_query()`` and read ``.value``:
+
+            >>> df = file.read_dataframe().execute_query().value
+        """
+        from office365.runtime.converters.dataframe import DataFrameResult, dataframe_from_bytes
+
+        result = DataFrameResult(self.context)
+
+        def _convert(return_type: ClientResult[bytes]) -> None:
+            result.set_property("__value", dataframe_from_bytes(return_type.value, format, **opts))
+
+        self.get_content().after_execute(_convert)
+        return result
+
+    def write_dataframe(self, df, *, format: str = "csv", index: bool = False, **opts) -> Self:  # noqa: A002
+        """Write a pandas DataFrame to this file's **content** (deferred).
+
+        Serializes the frame (CSV is UTF-8 with a BOM) and queues a
+        ``SaveBinaryStream``; run with ``execute_query()``. This replaces the
+        file content, not its metadata.
+        """
+        from office365.runtime.converters.dataframe import dataframe_to_bytes
+
+        return self.save_binary_stream(dataframe_to_bytes(df, format, index, **opts))
+
     def get_exists(self) -> ClientResult[bool]:
         result = ClientResult(self.context, bool())
         result.set_property("__value", False)
@@ -272,6 +304,22 @@ class File(AbstractFile):
         self.context.add_query(qry)
         return return_type
 
+    def delete_object(self, bypass_shared_lock: bool = False) -> Self:
+        """Deletes the file.
+
+        Args:
+            bypass_shared_lock: Send ``Prefer: bypass-shared-lock`` so the delete
+                succeeds even when the file is open for editing. Without it the
+                server rejects the request with
+                :class:`~office365.runtime.exceptions.FileLockedException` (HTTP 423).
+        """
+        super().delete_object()
+        if bypass_shared_lock:
+            from office365.runtime.http.prefer import prefer_bypass_shared_lock
+
+            self.context.before_execute(prefer_bypass_shared_lock, once=True)
+        return self
+
     def recycle(self) -> ClientResult[str]:
         """Moves the file to the Recycle Bin and returns the identifier of the new Recycle Bin item."""
         return_type = ClientResult(self.context, str())
@@ -686,10 +734,9 @@ class File(AbstractFile):
         # OData literals escape embedded single quotes by doubling them (' -> '')
         decoded_server_relative_url = decoded.replace("'", "''")
 
-        url = quote(
-            rf"{context.service_root_url}/web/getFileByServerRelativePath"
-            rf"(DecodedUrl='{decoded_server_relative_url}')/\$value",
-            safe=":/",
+        url = (
+            f"{context.service_root_url}/web/getFileByServerRelativePath"
+            f"(DecodedUrl='{quote(decoded_server_relative_url)}')/$value"
         )
 
         request = RequestOptions(url)
@@ -711,10 +758,9 @@ class File(AbstractFile):
         # OData literals escape embedded single quotes by doubling them (' -> '')
         decoded_server_relative_url = decoded.replace("'", "''")
 
-        url = quote(
-            rf"{context.service_root_url}/web/getFileByServerRelativePath("
-            rf"DecodedUrl='{decoded_server_relative_url}')/\$value",
-            safe=":/",
+        url = (
+            f"{context.service_root_url}/web/getFileByServerRelativePath"
+            f"(DecodedUrl='{quote(decoded_server_relative_url)}')/$value"
         )
 
         request = RequestOptions(url)

office365/sharepoint/files/versions/version.py

@@ -5,7 +5,6 @@ from typing_extensions import Self
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.paths.resource_path import ResourcePath
-from office365.runtime.paths.v3.entity import EntityPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.types.odata_property import odata
 from office365.sharepoint.entity import Entity
@@ -57,10 +56,7 @@ class FileVersion(Entity):
         """Gets the user that created the file version."""
         from office365.sharepoint.principal.users.user import User
 
-        return self.properties.get(
-            "CreatedBy",
-            User(self.context, ResourcePath("CreatedBy", self.resource_path)),
-        )
+        return self.properties.get("CreatedBy", User(self.context, ResourcePath("CreatedBy", self.resource_path)))
 
     @property
     def id(self) -> Optional[int]:
@@ -87,12 +83,41 @@ class FileVersion(Entity):
         """Gets a value that specifies the check-in comment."""
         return self.properties.get("CheckInComment", None)
 
-    def set_property(self, key, value, persist_changes=True):  # type: ignore[override]
-        super().set_property(key, value, persist_changes)
-        if key.lower() == self.property_ref_name.lower():
-            assert self.parent_collection is not None
-            if self._resource_path is None:
-                self._resource_path = EntityPath(value, self.parent_collection.resource_path)
-            else:
-                self._resource_path.set_segment(value)
+    @property
+    def check_in_comment(self) -> Optional[str]:
+        """Gets the CheckInComment property"""
+        return self.properties.get("CheckInComment", None)
+
+    @property
+    def expiration_date(self) -> Optional[str]:
+        """Gets the ExpirationDate property"""
+        return self.properties.get("ExpirationDate", None)
+
+    @property
+    def length(self) -> Optional[int]:
+        """Gets the Length property"""
+        return self.properties.get("Length", None)
+
+    @property
+    def size(self) -> Optional[int]:
+        """Gets the Size property"""
+        return self.properties.get("Size", None)
+
+    @property
+    def snapshot_date(self) -> Optional[str]:
+        """Gets the SnapshotDate property"""
+        return self.properties.get("SnapshotDate", None)
+
+    @property
+    def property_ref_name(self) -> str:
+        return "ID"
+
+    def set_expiration_date(self, expiration_date: datetime) -> Self:
+        """SetExpirationDate operation.
+
+        Args:
+            expiration_date (datetime): expirationDate parameter
+        """
+        qry = ServiceOperationQuery(self, "SetExpirationDate", None, {"expirationDate": expiration_date}, None, None)
+        self.context.add_query(qry)
         return self

office365/sharepoint/folders/collection.py

@@ -10,12 +10,16 @@ from office365.sharepoint.folders.coloring_information import (
 )
 from office365.sharepoint.folders.colors import FolderColors
 from office365.sharepoint.folders.folder import Folder
+from office365.sharepoint.thresholds import LIST_VIEW_THRESHOLD
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 
 class FolderCollection(EntityCollection[Folder]):
     """Represents a collection of Folder resources."""
 
+    _list_view_threshold = LIST_VIEW_THRESHOLD
+    _truncation_hint = "page it with folders.get_all(page_size=2000)"
+
     def __init__(self, context, resource_path=None, parent=None):
         super().__init__(context, Folder, resource_path, parent)