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

office365/migration/assessor.py

@@ -1,243 +0,0 @@
-"""
-Pre-migration assessment — surface blockers and warnings before touching data.
-
-Follows deferred execution pattern::
-
-    from office365.migration import MigrationAssessor
-
-    report = MigrationAssessor(ctx.web)\
-        .include_permissions()\
-        .include_versions()\
-        .execute_query()
-
-    print(report.summary())
-    print(report.blockers)
-    report.to_excel("assessment.xlsx")
-    df = report.to_dataframe()
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from office365.migration.assessment.issue import AssessmentIssue
-from office365.migration.assessment.report import AssessmentReport
-from office365.runtime.client_result import ClientResult
-from office365.sharepoint.entity import Entity
-from office365.sharepoint.fields.collection import FieldCollection
-from office365.sharepoint.listitems.collection import ListItemCollection
-from office365.sharepoint.lists.collection import ListCollection
-from office365.sharepoint.lists.list import List
-
-if TYPE_CHECKING:
-    from office365.sharepoint.webs.web import Web
-
-
-# ── Known problematic field names (from issue #688 and MigrationAssessor memory) ──
-
-APPROVAL_WORKFLOW_FIELDS = {
-    "_ApprovalStatus",
-    "_ApprovalRespondedBy",
-    "_ApprovalAssignedTo",
-}
-
-# Attrs that must be stripped before migrating field XML
-STRIP_FIELD_ATTRS = {"ReadOnly", "ColName", "RowOrdinal", "SourceID", "Version"}
-
-# SharePoint path/name constraints
-MAX_PATH_LENGTH = 400
-MAX_NAME_LENGTH = 128
-INVALID_CHARS = set(r'~"#%&*:<>?/\{|}')
-LARGE_FILE_BYTES = 15 * 1024 * 1024 * 1024  # 15GB — SPMT limit
-
-
-class MigrationAssessor(Entity):
-    """
-    Pre-migration assessment. Surfaces blockers and warnings before
-    any data is moved.
-
-    Example::
-
-        report = MigrationAssessor(ctx.web)\
-            .include_permissions()\
-            .execute_query()
-
-    """
-
-    def __init__(self, web: Web) -> None:
-        super().__init__(web.context)
-        self._web = web
-        self._check_paths = True
-        self._check_fields = True
-        self._check_files = True
-        self._check_permissions = False
-        self._check_versions = False
-
-    def include_permissions(self) -> "MigrationAssessor":
-        """Include unique permissions scan (expensive — many API calls)."""
-        self._check_permissions = True
-        return self
-
-    def include_versions(self) -> "MigrationAssessor":
-        """Include version history in size estimates."""
-        self._check_versions = True
-        return self
-
-    def skip_path_checks(self) -> "MigrationAssessor":
-        self._check_paths = False
-        return self
-
-    def skip_field_checks(self) -> "MigrationAssessor":
-        self._check_fields = False
-        return self
-
-    # ── Execution ─────────────────────────────────────────────────
-
-    def assess(self) -> ClientResult[AssessmentReport]:
-        """Run the assessment. Returns AssessmentReport."""
-
-        return_type = ClientResult[AssessmentReport](self.context, AssessmentReport())
-
-        def _assess(lists: ListCollection):
-            return_type.value.total_lists = len(lists)
-            for lst in lists:
-                if lst.hidden:
-                    continue
-
-                if self._check_fields:
-                    lst.fields.get().after_execute(lambda col, lst=lst: self._assess_fields(lst, col, return_type.value))
-                if (self._check_paths or self._check_files) and lst.base_type == 1:
-                    lst.items.select(["FileRef", "FileLeafRef", "File/Length"]).expand(["File"]).get().after_execute(
-                        lambda col, lst=lst: self._assess_items(col, return_type.value)
-                    )
-                if self._check_permissions:
-                    lst.items.select(["HasUniqueRoleAssignments", "FileRef"]).get_all().after_execute(
-                        lambda col, lst=lst: self._assess_permissions(lst, col, return_type.value)
-                    )
-
-        self._web.lists.get().after_execute(_assess)
-
-        return return_type
-
-    def _flag(
-        self,
-        report: AssessmentReport,
-        severity: str,
-        category: str,
-        location: str,
-        message: str,
-        suggestion: str = "",
-    ) -> None:
-        report.issues.append(AssessmentIssue(severity, category, location, message, suggestion))
-
-    def _assess_fields(self, lst: List, fields: FieldCollection, report: AssessmentReport) -> None:
-        """Check site columns for migration blockers."""
-
-        for f in fields:
-            name = f.properties.get("InternalName", "")
-            schema = f.properties.get("SchemaXml", "")
-            location = f"lists/{lst.title}/{name}"
-
-            # ReadOnly fields
-            if 'ReadOnly="TRUE"' in schema:
-                self._flag(
-                    report,
-                    "warning",
-                    "field",
-                    location,
-                    "ReadOnly field — cannot be written to via REST API",
-                    "Strip ReadOnly attribute from SchemaXml before migrating",
-                )
-
-            # Approval workflow fields
-            if name in APPROVAL_WORKFLOW_FIELDS:
-                self._flag(
-                    report,
-                    "blocker",
-                    "workflow",
-                    location,
-                    f"{name} is a system approval workflow field — cannot be migrated",
-                    "Enable EnableModeration=True on destination list to recreate natively",
-                )
-
-            # Schema attrs that must be stripped
-            dirty_attrs = [attr for attr in STRIP_FIELD_ATTRS if f'{attr}="' in schema]
-            if dirty_attrs:
-                self._flag(
-                    report,
-                    "warning",
-                    "field",
-                    location,
-                    f"Schema contains internal attrs that must be stripped: {dirty_attrs}",
-                    f"Strip before migrating: {STRIP_FIELD_ATTRS}",
-                )
-
-    def _assess_items(self, items: ListItemCollection, report: AssessmentReport) -> None:
-        """Check files and paths for blockers."""
-
-        for item in items:
-            report.total_files += 1
-            path = item.properties.get("FileRef", "")
-            name = item.properties.get("FileLeafRef", "")
-            size = item.file.length or 0
-            report.total_size_gb += size / 1024 / 1024 / 1024
-
-            # path length
-            if self._check_paths and len(path) > MAX_PATH_LENGTH:
-                self._flag(
-                    report,
-                    "blocker",
-                    "path",
-                    path,
-                    f"Path length {len(path)} exceeds SharePoint limit of {MAX_PATH_LENGTH}",
-                    "Shorten folder names or restructure hierarchy",
-                )
-
-            # name length
-            if self._check_paths and len(name) > MAX_NAME_LENGTH:
-                self._flag(
-                    report,
-                    "blocker",
-                    "path",
-                    path,
-                    f"File name length {len(name)} exceeds limit of {MAX_NAME_LENGTH}",
-                    "Rename file before migration",
-                )
-
-            # invalid characters
-            if self._check_paths:
-                bad = [c for c in name if c in INVALID_CHARS]
-                if bad:
-                    self._flag(
-                        report,
-                        "blocker",
-                        "path",
-                        path,
-                        f"File name contains invalid chars: {bad}",
-                        "Rename file — remove invalid characters",
-                    )
-
-            # large files
-            if self._check_files and size > LARGE_FILE_BYTES:
-                self._flag(
-                    report,
-                    "warning",
-                    "file",
-                    path,
-                    f"File size {size / 1024 / 1024 / 1024:.1f}GB exceeds SPMT 15GB limit",
-                    "Use chunked upload or split the file",
-                )
-
-    def _assess_permissions(self, lst: List, items: ListItemCollection, report: AssessmentReport) -> None:
-        """Check for broken permission inheritance (expensive)."""
-
-        unique_count = sum(1 for i in items if i.properties.get("HasUniqueRoleAssignments", False))
-        if unique_count > 0:
-            self._flag(
-                report,
-                "warning",
-                "permission",
-                f"lists/{lst.title}",
-                f"{unique_count} items have unique permissions",
-                "Set preserve_permissions=True in MigrationOptions (slower migration)",
-            )

office365/onedrive/termstore/store_exporter.py

@@ -1,40 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from office365.onedrive.termstore.sets.collection import SetCollection
-from office365.onedrive.termstore.terms.collection import TermCollection
-from office365.runtime.client_result import ClientResult
-
-if TYPE_CHECKING:
-    from office365.onedrive.termstore.groups.collection import GroupCollection
-    from office365.onedrive.termstore.store import Store
-
-
-class StoreExporter:
-    def __init__(self, store: Store):
-        self.store = store
-
-    def export(self) -> ClientResult[list[dict]]:
-        return_type = ClientResult(self.store.context, [])
-
-        def _on_groups_loaded(groups: GroupCollection):
-            for g in groups:
-                gd = {"name": g.display_name, "sets": []}
-                return_type.value.append(gd)
-                g.sets.get().after_execute(lambda sets, gd=gd: _on_sets_loaded(sets, gd))
-
-        def _on_sets_loaded(sets: SetCollection, group_data: dict):
-            for s in sets:
-                sd = {"name": s.display_name, "children": []}
-                group_data["sets"].append(sd)
-                s.children.get().after_execute(lambda terms, sd=sd: _on_terms_loaded(terms, sd))
-
-        def _on_terms_loaded(terms: TermCollection, parent_item: dict):
-            for term in terms:
-                child = {"name": term.display_name}
-                parent_item.setdefault("children", []).append(child)
-                term.children.get().after_execute(lambda t, c=child: _on_terms_loaded(t, c))
-
-        self.store.groups.get().after_execute(_on_groups_loaded)
-        return return_type

office365/onedrive/termstore/store_importer.py

@@ -1,34 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from office365.onedrive.termstore.terms.collection import TermCollection
-
-if TYPE_CHECKING:
-    from office365.onedrive.termstore.store import Store
-
-
-class StoreImporter:
-    def __init__(self, store: Store):
-        self.store = store
-
-    def import_from_data(self, data: list[dict]) -> Store:
-        """Import term hierarchy from a parsed JSON list.
-
-        Args:
-            data: List of group dicts matching the export format.
-
-        Returns:
-            self.store for chaining — call .context.execute_query() to process.
-        """
-        for group_data in data:
-            group = self.store.groups.get_or_add(group_data["name"])
-            for set_data in group_data.get("sets", []):
-                term_set = group.sets.get_or_add(set_data["name"])
-                self._import_terms(term_set.children, set_data.get("children", []))
-        return self.store
-
-    def _import_terms(self, collection: TermCollection, terms: list[dict]):
-        for t in terms:
-            node = collection.get_or_add(t["name"])
-            self._import_terms(node.children, t.get("children", []))

office365/runtime/csv_writer.py

@@ -1,77 +0,0 @@
-"""CSV exporter for ClientObjectCollection — reuses .select() + .expand()."""
-
-from __future__ import annotations
-
-import csv
-from typing import IO, TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from office365.runtime.client_object import ClientObject
-    from office365.runtime.client_object_collection import ClientObjectCollection
-
-
-class CollectionCsvWriter:
-    """Write collection items to CSV using query_options.select + .expand.
-
-    Plain select fields (e.g. ``"displayName"``) produce one column.
-    Dotted select fields (e.g. ``"members/displayName"``) walk into an
-    expanded navigation property — one CSV row is emitted per child item.
-
-    Usage:
-        >>> client.teams.get_all() \\
-        ...     .select(["displayName", "members/displayName", "members/email"]) \\
-        ...     .expand(["members"]) \\
-        ...     .to_csv(f) \\
-        ...     .execute_query()
-    """
-
-    def __init__(self, collection: ClientObjectCollection, file: IO) -> None:
-        self._collection: ClientObjectCollection = collection
-        self._file: IO = file
-
-    def write(self) -> None:
-        items: list[ClientObject] = list(self._collection)
-        if not items:
-            return
-
-        select: list[str] = self._collection.query_options.select
-        expand: set[str] = set(self._collection.query_options.expand)
-
-        plain: list[str] = [f for f in select if "/" not in f]
-        dotted: list[list[str]] = [f.split("/", 1) for f in select if "/" in f]
-
-        w = csv.writer(self._file)
-        w.writerow(select)
-
-        for item in items:
-            children: list[dict[str, Any]] | list[ClientObject] = self._resolve_children(item, dotted, expand)
-            base = [str(item.properties.get(k, "")) for k in plain]
-            for child in children:
-                row = list(base)
-                for _nav, prop in dotted:
-                    row.append(self._child_val(child, prop))
-                w.writerow(row)
-
-    @staticmethod
-    def _resolve_children(
-        item: ClientObject,
-        dotted: list[list[str]],
-        expand: set[str],
-    ) -> list[dict[str, Any]] | list[ClientObject]:
-        for nav, _ in dotted:
-            if nav not in expand:
-                continue
-            raw: Any = item.properties.get(nav)
-            if raw is None:
-                return [{}]
-            if hasattr(raw, "_data"):
-                return list(raw._data) or [{}]
-            return [raw]
-        return [{}]
-
-    @staticmethod
-    def _child_val(child: Any, key: str) -> str:
-        """Read a property from a child item that may be a ClientObject or dict."""
-        if isinstance(child, dict):
-            return str(child.get(key, ""))
-        return str(child.properties.get(key, ""))

office365/runtime/odata/member.py

@@ -1,14 +0,0 @@
-from dataclasses import dataclass
-from typing import Optional
-
-
-@dataclass
-class MemberInformation:
-    """Represents a member in an OData entity model.
-
-    Attributes:
-        Name: The name of the member
-    """
-
-    Name: str = ""
-    Value: Optional[str] = None

office365/runtime/odata/method.py

@@ -1,19 +0,0 @@
-from dataclasses import dataclass
-from typing import List, Optional
-
-
-@dataclass
-class MethodInformation:
-    """Represents an executable OData operation (function/action).
-
-    Attributes:
-        Name: Method name as defined in OData metadata
-        IsBeta: Whether this is a preview/beta method
-        Parameters: List of accepted parameter names
-        ReturnTypeFullName: Fully qualified return type name
-    """
-
-    Name: Optional[str] = None
-    IsBeta: Optional[bool] = None
-    Parameters: Optional[List[str]] = None
-    ReturnTypeFullName: Optional[str] = None

office365/runtime/odata/model.py

@@ -1,54 +0,0 @@
-from typing import Dict
-
-from typing_extensions import Self
-
-from office365.runtime.odata.type_information import TypeInformation
-
-
-class ODataModel:
-    """Represents the type system metadata for an OData service.
-
-    Maintains a registry of entity and complex types that make up the service's data model.
-    """
-
-    def __init__(self):
-        self._types: Dict[str, TypeInformation] = {}
-
-    @property
-    def types(self) -> Dict[str, TypeInformation]:
-        """Gets the type mapping dictionary.
-
-        Returns:
-            A dictionary mapping type names to their schemas
-        """
-        return self._types
-
-    def add_type(self, type_schema: TypeInformation) -> Self:
-        """Registers a type schema in the model.
-
-        Args:
-            type_schema: The type schema to register
-
-        Returns:
-            The registered type schema (for method chaining)
-
-        Example:
-            >>> model = ODataModel()
-            >>> model.add_type(TypeInformation("SP.User"))
-        """
-        self._types[type_schema.FullName] = type_schema
-        return self
-
-    def get_type(self, type_name: str) -> TypeInformation:
-        """Retrieves a type schema by name.
-
-        Args:
-            type_name: The name of the type to retrieve
-
-        Returns:
-            The type schema if found
-
-        Raises:
-            KeyError: If the type is not registered
-        """
-        return self._types[type_name]

office365/runtime/odata/parameter.py

@@ -1,19 +0,0 @@
-from dataclasses import dataclass
-from typing import Optional
-
-
-@dataclass
-class ParameterInformation:
-    """Represents a parameter in an OData operation (function/action).
-
-    Attributes:
-        Name: The name of the parameter as defined in the OData metadata.
-              This should match exactly with the server's expected parameter name.
-
-        ParameterTypeFullName: The fully qualified type name of the parameter.
-                              Format is "Namespace.Type" (e.g., "Edm.String").
-                              Used for type checking and serialization.
-    """
-
-    Name: Optional[str] = None
-    ParameterTypeFullName: Optional[str] = None

office365/runtime/odata/property.py

@@ -1,19 +0,0 @@
-from dataclasses import dataclass
-from typing import Optional
-
-
-@dataclass
-class PropertyInformation:
-    """Represents a property in an OData entity model.
-
-    Attributes:
-        Name: The name of the property
-        ReadOnly: Whether the property is read-only
-    """
-
-    Name: str = ""
-    TypeName: Optional[str] = None
-    ReadOnly: Optional[bool] = None
-    IsBeta: Optional[bool] = None
-    ExcludeFromDefaultRetrieval: Optional[bool] = None
-    IsNavigation: Optional[bool] = False

office365/runtime/odata/query_options_builder.py

@@ -1,38 +0,0 @@
-from typing import List, Optional
-
-from office365.runtime.client_object import ClientObject
-from office365.runtime.client_object_collection import ClientObjectCollection
-from office365.runtime.odata.query_options import QueryOptions
-
-
-class QueryOptionsBuilder:
-    """Builder for constructing QueryOptions instances."""
-
-    @staticmethod
-    def build(client_object: ClientObject, properties_to_include: Optional[List[str]] = None) -> QueryOptions:
-        """Builds optimized query options for the given client object.
-
-        Args:
-            client_object: The target client object or collection
-            properties_to_include: Properties to include in $select/$expand
-
-        Returns:
-            Configured QueryOptions instance
-        """
-        query_options = client_object.query_options
-        if properties_to_include is None:
-            return query_options
-
-        for name in properties_to_include:
-            if name in query_options.select:
-                continue
-
-            if isinstance(client_object, ClientObjectCollection):
-                prop = client_object.create_typed_object().get_property(name)
-            else:
-                prop = client_object.get_property(name)
-
-            if name == "Properties" or isinstance(prop, ClientObject):
-                query_options.expand.append(name)
-            query_options.select.append(name)
-        return query_options

office365/runtime/odata/reader.py

@@ -1,99 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import Dict, Optional
-from xml.etree import ElementTree as ET
-from xml.etree.ElementTree import Element
-
-from office365.runtime.odata.member import MemberInformation
-from office365.runtime.odata.model import ODataModel
-from office365.runtime.odata.property import PropertyInformation
-from office365.runtime.odata.type_information import TypeInformation
-
-
-def _normalize_class_name(name: str) -> str:
-    return name[0].upper() + name[1:]
-
-
-class ODataReader(ABC):
-    """OData reader"""
-
-    def __init__(self, metadata_path: str):
-        self._metadata_path = metadata_path
-        self._root: Optional[Element] = None
-
-    @property
-    @abstractmethod
-    def xml_namespaces(self) -> Dict[str, str]:
-        """XML namespaces for the specific OData version"""
-
-    def format_file(self):
-        import xml.dom.minidom
-
-        with open(self._metadata_path, "r", encoding="utf8") as in_file:
-            metadata_content = in_file.read()
-
-        formatted_metadata_content = xml.dom.minidom.parseString(metadata_content).toprettyxml()
-
-        with open(self._metadata_path, "w", encoding="utf8") as out_file:
-            out_file.write(formatted_metadata_content)
-
-    def process_schema_node(self, model: ODataModel) -> None:
-        self._root = ET.parse(self._metadata_path).getroot()
-        schema_nodes = self._root.findall("edmx:DataServices/xmlns:Schema", self.xml_namespaces)
-
-        base_types = ["ComplexType", "EntityType", "EnumType"]
-
-        for base_type in base_types:
-            for schema_node in schema_nodes:
-                for type_node in schema_node.findall(f"xmlns:{base_type}", self.xml_namespaces):
-                    type_schema = self.process_type_node(type_node, schema_node, base_type)
-                    model.add_type(type_schema)
-
-    def process_type_node(self, type_node: Element, schema_node: Element, base_type: str) -> TypeInformation:
-        type_schema = TypeInformation()
-        type_name = type_node.get("Name")
-        if type_name is None:
-            raise ValueError("Type node missing 'Name' attribute")
-        type_schema.FullName = f"{schema_node.attrib['Namespace']}.{_normalize_class_name(type_name)}"
-        type_schema.BaseTypeFullName = base_type
-        type_schema.IsValueObject = base_type == "EntityType"
-
-        if base_type == "EnumType":
-            for member_node in type_node.findall("xmlns:Member", self.xml_namespaces):
-                schema = self.process_member_node(member_node)
-                type_schema.add_member(schema)
-        else:
-            for prop_node in type_node.findall("xmlns:Property", self.xml_namespaces):
-                schema = self.process_property_node(prop_node)
-                type_schema.add_property(schema)
-
-            for prop_node in type_node.findall("xmlns:NavigationProperty", self.xml_namespaces):
-                schema = self.process_navigation_property_node(prop_node)
-                if schema:
-                    type_schema.add_property(schema)
-
-        return type_schema
-
-    @abstractmethod
-    def process_method_node(self):
-        pass
-
-    @abstractmethod
-    def process_navigation_property_node(self, node: Element) -> Optional[PropertyInformation]:
-        pass
-
-    def process_property_node(self, node: Element) -> PropertyInformation:
-        schema = PropertyInformation()
-        schema.Name = node.get("Name") or ""
-        schema.TypeName = node.get("Type")
-        return schema
-
-    def process_member_node(self, node: Element) -> MemberInformation:
-        schema = MemberInformation()
-        schema.Name = node.get("Name") or ""
-        schema.Value = node.get("Value")
-        return schema
-
-    def generate_model(self):
-        model = ODataModel()
-        self.process_schema_node(model)
-        return model