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

office365/migration/session.py

@@ -1,24 +1,41 @@
-"""Migration session — coordinate a batch of migrations.
-
-A session runs one or more :class:`MigrationJob` together. Each job is one
-source → target migration; add it explicitly and start the whole batch::
-
-    session = MigrationSession()
-    job = session.add_task(FileSystemSource("src"), SharePointLibraryTarget(folder))
-    session.start()
-    print(session.status())
-    session.stop()
-    session.unregister()
+"""Migration session — the SPMT-shaped facade over a batch of migrations.
+
+Mirrors the ``Microsoft.SharePoint.MigrationTool.PowerShell`` cmdlets:
+
+| cmdlet | method |
+|---|---|
+| ``Register-SPMTMigration`` | :meth:`MigrationSession.register` |
+| ``Get-SPMTMigration`` | :meth:`MigrationSession.get` |
+| ``Add-SPMTTask`` | :meth:`MigrationSession.add_task` |
+| ``Remove-SPMTTask`` | :meth:`MigrationSession.remove_task` |
+| ``Show-SPMTMigration`` | :meth:`MigrationSession.show` |
+| ``Start-SPMTMigration`` | :meth:`MigrationSession.start` |
+| ``Stop-SPMTMigration`` | :meth:`MigrationSession.stop` |
+| ``Unregister-SPMTMigration`` | :meth:`MigrationSession.unregister` |
+
+A task pairs a source and a target adapter — either supplied directly, or
+declared as a :class:`~office365.migration.tasks.MigrationTask` (resolved against
+the registered ``ClientContext``).
 """
 
 from __future__ import annotations
 
+import itertools
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
 from office365.migration.base import MigrationOptions, MigrationPhase
 from office365.migration.job import MigrationJob
 
+if TYPE_CHECKING:
+    from office365.migration.settings import MigrationSettings
+    from office365.migration.tasks import MigrationTask
+
+__all__ = ["MigrationSession", "SessionTask"]
+
 
 def _job_status(job: MigrationJob) -> dict:
-    """Project a job's state — the status form of a session."""
+    """Project a job's state — the status form of a session task."""
     return {
         "source": job.source_label,
         "target": job.target_label,
@@ -33,34 +50,72 @@ def _job_status(job: MigrationJob) -> dict:
     }
 
 
-class MigrationSession:
-    """A batch of :class:`MigrationJob` tasks, run together.
+@dataclass
+class SessionTask:
+    """A registered task: an id, its descriptor (when declared), and its job."""
+
+    id: str
+    job: MigrationJob
+    descriptor: "MigrationTask | None" = None
 
-    Tasks are added explicitly with their own source/target (``options`` falls
-    back to the session's defaults when omitted)::
+    def status(self) -> dict:
+        data = _job_status(self.job)
+        data["id"] = self.id
+        if self.descriptor is not None:
+            data["descriptor"] = self.descriptor.label()
+        return data
 
-        session = MigrationSession()
-        job = session.add_task(FileSystemSource("src"), SharePointLibraryTarget(folder))
-        session.start()
-    """
 
-    def __init__(self, options: MigrationOptions | None = None) -> None:
+class MigrationSession:
+    """A batch of migration tasks, driven like the SPMT PowerShell cmdlets."""
+
+    def __init__(self, options: MigrationOptions | None = None, context=None, settings=None) -> None:
         self._options = options
-        self._jobs: list[MigrationJob] = []
+        self._context = context
+        self._settings = settings
+        self._tasks: list[SessionTask] = []
+        self._ids = itertools.count(1)
 
-    @property
-    def jobs(self) -> list[MigrationJob]:
-        return self._jobs
+    # ── Cmdlets ──────────────────────────────────────────────────
+
+    def register(self, settings: "MigrationSettings | None" = None, context=None) -> "MigrationSession":
+        """Register the session — its settings and the target ``ClientContext``."""
+        if settings is not None:
+            self._settings = settings
+        if context is not None:
+            self._context = context
+        return self
+
+    def get(self) -> "MigrationSession":
+        """The registered session (``Get-SPMTMigration``)."""
+        return self
 
     def add_task(
         self,
-        source,
-        target,
+        source=None,
+        target=None,
+        *,
+        task: "MigrationTask | None" = None,
         options: MigrationOptions | None = None,
         manifest_path=None,
         checkpoint_path=None,
+        **descriptor,
     ) -> MigrationJob:
-        """Add a migration task (a source → target :class:`MigrationJob`) to the session."""
+        """Add a task — adapters directly, a ``MigrationTask``, or task kwargs.
+
+        Descriptor kwargs (``file_share_source`` / ``target_site_url`` /
+        ``target_list`` …) are resolved against the registered context.
+        """
+        if task is None and descriptor:
+            from office365.migration.tasks import MigrationTask
+
+            task = MigrationTask(**descriptor)
+        if task is not None:
+            if self._context is None:
+                raise ValueError("register a ClientContext first (session.register(context=ctx))")
+            from office365.migration.sharepoint.resolvers import resolve_task
+
+            source, target = resolve_task(task, self._context, self._settings)
         job = MigrationJob(
             source,
             target,
@@ -68,38 +123,66 @@ class MigrationSession:
             manifest_path=manifest_path,
             checkpoint_path=checkpoint_path,
         )
-        self._jobs.append(job)
+        self._tasks.append(SessionTask(str(next(self._ids)), job, task))
         return job
 
+    def remove_task(self, task) -> None:
+        """Remove a task by its ``MigrationJob``, ``SessionTask`` or id."""
+        for entry in list(self._tasks):
+            if task in (entry, entry.job, entry.id):
+                self._tasks.remove(entry)
+                return
+        raise KeyError(task)
+
+    def show(self) -> list[dict]:
+        """The per-task status (``Show-SPMTMigration``)."""
+        return [entry.status() for entry in self._tasks]
+
     def start(self, progress=None) -> list[dict]:
         """Start the migration: plan + run every registered task."""
         statuses: list[dict] = []
-        for job in self._jobs:
-            if job.phase in (MigrationPhase.COMPLETED, MigrationPhase.COMPLETED_WITH_ERRORS, MigrationPhase.CANCELLED):
-                statuses.append(_job_status(job))
+        for entry in self._tasks:
+            job = entry.job
+            if job.phase in (
+                MigrationPhase.COMPLETED,
+                MigrationPhase.COMPLETED_WITH_ERRORS,
+                MigrationPhase.CANCELLED,
+            ):
+                statuses.append(entry.status())
                 continue
             job.plan(progress)
             job.run(progress)
-            statuses.append(_job_status(job))
+            statuses.append(entry.status())
         return statuses
 
-    def verify(self, spot_checks: int = 20):
-        """Reconcile source vs target for every task after migration."""
-        return [job.verify(spot_checks) for job in self._jobs]
-
-    def status(self) -> list[dict]:
-        """Get the current per-task status."""
-        return [_job_status(job) for job in self._jobs]
-
     def stop(self) -> None:
-        """Request a clean stop at the next batch boundary."""
-        for job in self._jobs:
-            job.pause()
+        """Cancel the session (``Stop-SPMTMigration``); tasks stay resumable."""
+        for entry in self._tasks:
+            entry.job.cancel()
 
-    def remove_task(self, job: MigrationJob) -> None:
-        """Remove a task (job) from the session."""
-        self._jobs.remove(job)
+    def pause(self) -> None:
+        """Request a clean stop at the next batch boundary (resumable)."""
+        for entry in self._tasks:
+            entry.job.pause()
 
     def unregister(self) -> None:
-        """Drop all tasks and release the session."""
-        self._jobs.clear()
+        """Drop all tasks and release the session (``Unregister-SPMTMigration``)."""
+        self._tasks.clear()
+
+    # ── State ────────────────────────────────────────────────────
+
+    @property
+    def tasks(self) -> list[SessionTask]:
+        return self._tasks
+
+    @property
+    def jobs(self) -> list[MigrationJob]:
+        return [entry.job for entry in self._tasks]
+
+    def status(self) -> list[dict]:
+        """The per-task status (alias of :meth:`show`)."""
+        return self.show()
+
+    def verify(self, spot_checks: int = 20):
+        """Reconcile source vs target for every task after migration."""
+        return [entry.job.verify(spot_checks) for entry in self._tasks]

office365/migration/settings.py

@@ -0,0 +1,67 @@
+"""Migration settings — the session-level surface (SPMT ``Register-SPMTMigration``).
+
+Mirrors the parameters of ``Microsoft.SharePoint.MigrationTool.PowerShell``'s
+``Register-SPMTMigration`` cmdlet (snake-cased) and maps the subset the core
+enforces onto :class:`~office365.migration.base.MigrationOptions`. Settings that
+only apply to the SPMT Windows tool (``working_folder``, ``enable_multi_round``,
+...) are kept for parity/documentation and ignored by the core.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from office365.migration.base import MigrationOptions
+
+__all__ = ["MigrationSettings"]
+
+
+@dataclass
+class MigrationSettings:
+    """Session-level migration settings (the ``Register-SPMTMigration`` surface)."""
+
+    migration_type: str = "Content"  # Content | Workflow
+    preserve_permissions: bool = False
+    preserve_inheritance: bool = True
+    preserve_versions: bool = False
+    keep_all_versions: bool = True
+    number_of_versions: int = 10
+    include_hidden_files: bool = True
+    migrate_files_created_after: str | None = None
+    migrate_files_modified_after: str | None = None
+    skip_files_with_extension: list[str] = field(default_factory=list)
+    skip_sites_with_name: str | None = None
+    skip_lists_with_name: str | None = None
+    skip_content_types_with_name: str | None = None
+    replacement_of_invalid_char: str | None = None
+    duplicate_page_behavior: str = "RENAME"
+    automatic_user_mapping: bool = True
+    user_mapping_file: str | None = None
+    # use the server-side Migration API (full fidelity: versions/ACLs) instead of
+    # client-side REST uploads — the SPMT path
+    use_migration_api: bool = False
+    use_custom_azure_storage: bool = False
+    custom_azure_storage_account: str | None = None
+    custom_azure_access_key: str | None = None
+    enable_encryption: bool = True
+    delete_temp_files_when_migration_done: bool = False
+    working_folder: str | None = None
+    enable_multi_round: bool = False
+    scan_only: bool = False
+    migrate_all_site_fields_and_content_types: bool = False
+    migrate_site_settings: str = "PRESERVE_ALL_SETTINGS"
+    migrate_navigation: bool = True
+    migrate_term_groups: bool = True
+    lookup_reference_policy: int = 0
+
+    def to_options(self, **overrides) -> MigrationOptions:
+        """Build :class:`MigrationOptions` from the settings (``overrides`` win)."""
+        values = {
+            "preserve_permissions": self.preserve_permissions,
+            "preserve_versions": self.preserve_versions,
+            "exclude_patterns": [f"*.{extension.lstrip('.')}" for extension in self.skip_files_with_extension],
+            "created_after": self.migrate_files_created_after,
+            "modified_after": self.migrate_files_modified_after,
+        }
+        values.update(overrides)
+        return MigrationOptions(**values)

office365/migration/sharepoint/__init__.py

@@ -11,6 +11,7 @@ from office365.migration.sharepoint.adapters import (
     SharePointListTarget,
 )
 from office365.migration.sharepoint.assessor import MigrationAssessor
+from office365.migration.sharepoint.options import SharePointAssessmentOptions
 from office365.migration.sharepoint.registry import (
     SHAREPOINT_SCANS,
     get_scan,
@@ -42,6 +43,7 @@ __all__ = [
     "PermissionScanner",
     "SHAREPOINT_SCANS",
     "ScanTarget",
+    "SharePointAssessmentOptions",
     "SharePointLibrarySource",
     "SharePointLibraryTarget",
     "SharePointListSource",

office365/migration/sharepoint/adapters.py

@@ -13,47 +13,44 @@ from __future__ import annotations
 import hashlib
 import io
 from collections.abc import Callable
+from datetime import timezone
 from typing import TYPE_CHECKING, cast
 
-from office365.migration._util import emit_progress, record_to_json
 from office365.migration.adapters import MigrationProgress
-from office365.migration.base import MigrationItem
+from office365.migration.base import MigrationItem, PermissionEntry
 from office365.migration.sharepoint.transfer import Failure
+from office365.runtime.converters.json_file import record_to_json
+from office365.runtime.converters.scalars import iso_or_none, parse_datetime, parse_int
+from office365.runtime.limits import DEFAULT_BATCH_SIZE
+from office365.runtime.operations import emit_progress
+from office365.sharepoint.fields.builtin_field_name import SYSTEM_FIELD_NAMES
 
 if TYPE_CHECKING:
     from office365.sharepoint.files.file import File
     from office365.sharepoint.folders.folder import Folder
     from office365.sharepoint.lists.list import List as SPList
+    from office365.sharepoint.permissions.roles.definitions.definition import RoleDefinition
 
 _TAXONOMY_FIELD_TYPES = {"TaxonomyFieldType", "TaxonomyFieldTypeMulti"}
 
-# Read-only bookkeeping columns that add no content and can require extra
-# permissions to project; never part of the fallback select.
-_SYSTEM_INTERNAL_NAMES = {
-    "ContentTypeId",
-    "ContentType",
-    "Created",
-    "Modified",
-    "Author",
-    "Editor",
-    "FileRef",
-    "FileDirRef",
-    "FileLeafRef",
-    "File_x0020_Type",
-    "FSObjType",
-    "ID",
-    "GUID",
-    "UniqueId",
-    "PermMask",
-    "MetaInfo",
-    "owshiddenversion",
-    "AppAuthor",
-    "AppEditor",
-    "VirusStatus",
-    "ScopeId",
-    "InstanceID",
-    "Order",
-}
+# Always-projected system metadata (reliable author/editor identity).
+_METADATA_SELECT = ["AuthorId", "EditorId"]
+
+
+def _sp_timestamp(value: str | None) -> str | None:
+    """Normalize an ISO-8601 timestamp to the ``...Z`` UTC form SharePoint expects.
+
+    ``ValidateUpdateListItem`` (``datesInUTC=True``) rejects the ``+00:00`` offset
+    form the migration items carry, so convert to a naive UTC ``Z`` string.
+    """
+    if not value:
+        return None
+    parsed = parse_datetime(value)
+    if parsed is None:
+        return value
+    if parsed.tzinfo is not None:
+        parsed = parsed.astimezone(timezone.utc).replace(tzinfo=None)
+    return parsed.strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
 def is_taxonomy_validation(exc: Exception) -> bool:
@@ -117,9 +114,10 @@ class SharePointListSource:
 
     def _load_items(self, select: list[str] | None):
         items = self._list.items
-        if select:
-            items = items.select(select)
-        return items.get_all().execute_query()
+        # A full read projects ``*`` plus the system metadata so author/editor ids
+        # are captured reliably; an explicit/safe projection is honored as-is.
+        columns = ["*", *_METADATA_SELECT] if select is None else select
+        return items.select(columns).get_all().execute_query()
 
     def _safe_select(self) -> list[str]:
         """Fallback projection: visible, non-system columns minus Managed Metadata.
@@ -138,21 +136,29 @@ class SharePointListSource:
                 continue
             if internal_name.startswith("_") or getattr(field, "hidden", False):
                 continue  # hidden/system metadata — not safe to project
-            if internal_name in _SYSTEM_INTERNAL_NAMES:
+            if internal_name in SYSTEM_FIELD_NAMES:
                 continue
             columns.append(internal_name)
         return columns
 
     def _project(self, loaded, progress: MigrationProgress) -> list[MigrationItem]:
+        from office365.runtime.converters.records import iter_records
+
+        # Reuse the shared record projection (raw values, no JSON coercion) so the
+        # migration payload matches the data pipeline's.
+        records = iter_records(loaded, raw=True)
         result: list[MigrationItem] = []
-        for item in loaded:
-            record = {k: v for k, v in item.properties.items() if not str(k).startswith("__")}
+        for item, record in zip(loaded, records):
             self._records[str(item.id)] = record
             result.append(
                 MigrationItem(
                     source_path=f"{self._list.title}/{item.id}",
                     dest_path=str(item.id),
                     item_type="record",
+                    modified=iso_or_none(record.get("Modified")),
+                    created=iso_or_none(record.get("Created")),
+                    author_id=parse_int(record.get("AuthorId")),
+                    editor_id=parse_int(record.get("EditorId")),
                 )
             )
             emit_progress(progress, done=len(result), stage="planning", items=[item])
@@ -170,19 +176,81 @@ class SharePointListSource:
 
 
 class SharePointListTarget:
-    """Imports record payloads into a SharePoint list via ``from_records``."""
+    """Imports record payloads into a SharePoint list.
 
-    def __init__(self, target_list: "SPList") -> None:
+    Pass ``key`` (one or more natural-key columns) to make the target idempotent:
+    a hash of those columns is stored in ``key_field`` and each payload is created
+    or (``on_conflict="upsert"``) updated, so re-runs never duplicate. Without a
+    key, records are appended and idempotency relies on the checkpoint/manifest.
+    """
+
+    def __init__(
+        self,
+        target_list: "SPList",
+        key: str | list[str] | None = None,
+        key_field: str = "MigrationKey",
+        on_conflict: str = "skip",
+    ) -> None:
         self._list = target_list
+        self._key_columns = [key] if isinstance(key, str) else (list(key) if key else [])
+        self._key_field = key_field
+        self._on_conflict = on_conflict
+        self._target = None
+        self._existing: dict = {}
 
     def label(self) -> str:
         return f"list:{self._list.title}"
 
     def exists(self, item: MigrationItem) -> bool:
-        return False  # records are appended; idempotency via manifest/checkpoint
+        # Keyed dedup happens in _queue (the key is derived from the payload, which
+        # exists() doesn't receive); without a key, records are appended.
+        return False
 
     def write(self, item: MigrationItem, payload: object) -> None:
-        self._list.items.from_records([cast(dict, payload)])
+        self._queue([cast(dict, payload)])
+
+    def write_many(
+        self,
+        items: list[MigrationItem],
+        payloads: list[object],
+        concurrency: int = 1,
+    ) -> list[Failure]:
+        """Queue a chunk and flush it immediately, then discard the entities.
+
+        Flushing per chunk (instead of only at :meth:`commit`) keeps a large list
+        migration memory-bounded — the queued creates never accumulate for the
+        whole run.
+
+        Returns:
+            No failures (a batch failure raises; there are no partial successes).
+        """
+        self._queue([cast(dict, payload) for payload in payloads])
+        self._flush(len(payloads), concurrency)
+        return []
+
+    def _queue(self, records: list[dict]) -> None:
+        if not self._key_columns:
+            for record in records:
+                self._list.items.queue_records([record])
+            return
+        from office365.runtime.converters.upsert import keyed_queue
+        from office365.sharepoint.fields.name import internal_field_name
+
+        target = self._target
+        if target is None:
+            target = self._list.items.upsert_target(key_field=self._key_field)
+            target.ensure_key_field()
+            self._list.context.execute_query()
+            self._existing.update(target.load_keys())
+            self._target = target
+        key_columns = [internal_field_name(c) for c in self._key_columns]
+        keyed_queue(
+            target,
+            records,
+            key_columns=key_columns,
+            existing=self._existing,
+            on_conflict=self._on_conflict,
+        )
 
     def list_paths(self) -> list[str]:
         return [str(i.id) for i in self._list.items.get().execute_query()]
@@ -191,10 +259,16 @@ class SharePointListTarget:
         return ""
 
     def commit(self, options=None) -> None:
-        """Flush the queued record writes through an OData batch (JSON-only parallel mode)."""
-        batch_size = getattr(options, "batch_size", None) or 100
+        """Flush any remaining queued record writes through an OData batch."""
+        batch_size = getattr(options, "batch_size", None) or DEFAULT_BATCH_SIZE
         concurrency = getattr(options, "concurrency", None) or 1
+        self._flush(batch_size, concurrency)
+
+    def _flush(self, batch_size: int, concurrency: int) -> None:
+        if not self._list.context.has_pending_request:
+            return
         self._list.context.execute_batch(items_per_batch=batch_size, concurrency=concurrency)
+        self._list.items.clear()
 
     def close(self) -> None:
         pass
@@ -255,6 +329,10 @@ class SharePointLibrarySource:
                     dest_path=rel,
                     size_bytes=file.length or 0,
                     item_type="file",
+                    modified=iso_or_none(file.time_last_modified),
+                    created=iso_or_none(file.time_created),
+                    author_id=parse_int(file.author.id),
+                    editor_id=parse_int(file.modified_by.id),
                 )
             )
             emit_progress(progress, done=len(result), stage="planning", items=[file])
@@ -281,6 +359,32 @@ class SharePointLibrarySource:
             return hashlib.md5(b"").hexdigest()
         return hashlib.md5(self.read(item)).hexdigest()
 
+    def read_permissions(self, item: MigrationItem) -> list[PermissionEntry]:
+        """Read the item's role assignments (for best-effort ACL preservation).
+
+        Returns one :class:`PermissionEntry` per principal (user or group), keyed
+        by login name; empty for items with no unique assignments.
+        """
+        securable = self._securable(item)
+        if securable is None:
+            return []
+        assignments = securable.role_assignments.expand(["Member", "RoleDefinitionBindings"]).get().execute_query()
+        result: list[PermissionEntry] = []
+        for assignment in assignments:
+            member = assignment.member
+            name = member.login_name or member.user_principal_name
+            if not name:
+                continue
+            roles = [r.name for r in assignment.role_definition_bindings if r.name]
+            result.append(PermissionEntry(principal_name=name, roles=roles))
+        return result
+
+    def _securable(self, item: MigrationItem):
+        if item.item_type == "folder":
+            return self._folder.context.web.get_folder_by_server_relative_path(item.source_path).list_item_all_fields
+        file = self._files.get(item.dest_path)
+        return file.listItemAllFields if file is not None else None
+
     def close(self) -> None:
         pass
 
@@ -295,6 +399,7 @@ class SharePointLibraryTarget:
     def __init__(self, library_folder: "Folder", concurrency: int = 1) -> None:
         self._folder = library_folder
         self._concurrency = concurrency
+        self._role_definitions: dict[str, RoleDefinition] | None = None
 
     def label(self) -> str:
         return f"library:{self._folder.server_relative_url}"
@@ -347,6 +452,67 @@ class SharePointLibraryTarget:
         file.download(buffer).execute_query()
         return hashlib.md5(buffer.getvalue()).hexdigest()
 
+    def modified(self, item: MigrationItem) -> str:
+        """Last-modified of the target file (for incremental migration)."""
+        file = self._folder.context.web.get_file_by_server_relative_url(self._url(item)).get().execute_query()
+        return iso_or_none(file.time_last_modified) or ""
+
+    def apply_timestamps(self, item: MigrationItem) -> None:
+        """Best-effort: restore ``Created``/``Modified`` on the written item.
+
+        Uses ``ValidateUpdateListItem`` (the same mechanism as
+        ``ListItem.system_update``), which is the only REST path that can set these
+        system fields. ``preserve_versions`` still needs the server-side API.
+        """
+        form_values: dict[str, str] = {}
+        created = _sp_timestamp(item.created)
+        modified = _sp_timestamp(item.modified)
+        if created:
+            form_values["Created"] = created
+        if modified:
+            form_values["Modified"] = modified
+        if not form_values:
+            return
+        securable = self._securable(item)
+        if securable is None:
+            return
+        securable.validate_update_list_item(
+            form_values,
+            dates_in_utc=True,
+            new_document_update=item.item_type != "folder",
+        ).execute_query()
+
+    def apply_permissions(self, item: MigrationItem, permissions: list[PermissionEntry]) -> None:
+        """Best-effort: break inheritance and recreate the source role assignments.
+
+        Principals are resolved by login name on the target; roles that don't exist
+        there are skipped. This is a same-tenant copy — cross-tenant identity
+        mapping is out of scope.
+        """
+        securable = self._securable(item)
+        if securable is None:
+            return
+        securable.break_role_inheritance(copy_role_assignments=False, clear_sub_scopes=False)
+        for entry in permissions:
+            for role_name in entry.roles:
+                role = self._role_definition(role_name)
+                if role is not None:
+                    securable.add_role_assignment(entry.principal_name, role)
+        securable.context.execute_query()
+
+    def _securable(self, item: MigrationItem):
+        url = self._url(item).rstrip("/")
+        if item.item_type == "folder":
+            return self._folder.context.web.get_folder_by_server_relative_path(url).list_item_all_fields
+        return self._folder.context.web.get_file_by_server_relative_url(url).listItemAllFields
+
+    def _role_definition(self, name: str) -> "RoleDefinition | None":
+        """Resolve (and cache) a target role definition by name."""
+        if self._role_definitions is None:
+            loaded = self._folder.context.web.role_definitions.get().execute_query()
+            self._role_definitions = {rd.name: rd for rd in loaded if rd.name}
+        return self._role_definitions.get(name)
+
     def commit(self, options=None) -> None:
         pass