m365 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of m365 might be problematic. Click here for more details.

Files changed (85) hide show
  1. m365-0.1.0a1/GRAPH.md +389 -0
  2. m365-0.1.0a1/LICENSE +21 -0
  3. m365-0.1.0a1/MANIFEST.in +16 -0
  4. m365-0.1.0a1/PKG-INFO +132 -0
  5. m365-0.1.0a1/README.md +99 -0
  6. m365-0.1.0a1/assets/png/LOGO-LICENSE +21 -0
  7. m365-0.1.0a1/assets/png/m365-endorsed-lockup-horizontal-python-dark-957x323-384dpi.png +0 -0
  8. m365-0.1.0a1/assets/png/m365-endorsed-lockup-horizontal-python-light-957x323-384dpi.png +0 -0
  9. m365-0.1.0a1/assets/png/m365.png +0 -0
  10. m365-0.1.0a1/assets/svg/LOGO-LICENSE +21 -0
  11. m365-0.1.0a1/assets/svg/m365-endorsed-lockup-horizontal-python-dark.svg +178 -0
  12. m365-0.1.0a1/assets/svg/m365-endorsed-lockup-horizontal-python-light.svg +178 -0
  13. m365-0.1.0a1/assets/svg/m365.svg +30 -0
  14. m365-0.1.0a1/assets/third-party/ONEDRIVE-NOTICE.txt +15 -0
  15. m365-0.1.0a1/assets/third-party/OUTLOOK-NOTICE.txt +15 -0
  16. m365-0.1.0a1/assets/third-party/SHAREPOINT-NOTICE.txt +15 -0
  17. m365-0.1.0a1/assets/third-party/microsoft-onedrive.svg +1 -0
  18. m365-0.1.0a1/assets/third-party/microsoft-outlook.svg +2 -0
  19. m365-0.1.0a1/assets/third-party/microsoft-sharepoint.svg +1 -0
  20. m365-0.1.0a1/pyproject.toml +28 -0
  21. m365-0.1.0a1/setup.cfg +4 -0
  22. m365-0.1.0a1/setup.py +23 -0
  23. m365-0.1.0a1/src/m365/__init__.py +14 -0
  24. m365-0.1.0a1/src/m365/graph/__init__.py +73 -0
  25. m365-0.1.0a1/src/m365/graph/_core_dates.py +105 -0
  26. m365-0.1.0a1/src/m365/graph/_drive_walk.py +116 -0
  27. m365-0.1.0a1/src/m365/graph/_graph.py +474 -0
  28. m365-0.1.0a1/src/m365/graph/_legacy_paths.py +103 -0
  29. m365-0.1.0a1/src/m365/graph/_local_paths.py +90 -0
  30. m365-0.1.0a1/src/m365/graph/_mail_common.py +173 -0
  31. m365-0.1.0a1/src/m365/graph/_mail_graph.py +89 -0
  32. m365-0.1.0a1/src/m365/graph/_misc.py +90 -0
  33. m365-0.1.0a1/src/m365/graph/_site_resolution.py +216 -0
  34. m365-0.1.0a1/src/m365/graph/auth_types.py +103 -0
  35. m365-0.1.0a1/src/m365/graph/dateplumb/__init__.py +77 -0
  36. m365-0.1.0a1/src/m365/graph/dateplumb/_advanced.py +245 -0
  37. m365-0.1.0a1/src/m365/graph/dateplumb/base.py +914 -0
  38. m365-0.1.0a1/src/m365/graph/dateplumb/proxy.py +124 -0
  39. m365-0.1.0a1/src/m365/graph/mailbox.py +1579 -0
  40. m365-0.1.0a1/src/m365/graph/operations/__init__.py +65 -0
  41. m365-0.1.0a1/src/m365/graph/operations/doc_dispatch.py +118 -0
  42. m365-0.1.0a1/src/m365/graph/operations/doc_management.py +172 -0
  43. m365-0.1.0a1/src/m365/graph/operations/doc_sync.py +214 -0
  44. m365-0.1.0a1/src/m365/graph/operations/doc_transfer.py +342 -0
  45. m365-0.1.0a1/src/m365/graph/operations/mail_compose.py +208 -0
  46. m365-0.1.0a1/src/m365/graph/operations/mail_dispatch.py +92 -0
  47. m365-0.1.0a1/src/m365/graph/operations/mail_management.py +403 -0
  48. m365-0.1.0a1/src/m365/graph/operations/mail_transfer.py +182 -0
  49. m365-0.1.0a1/src/m365/graph/preprocessing/__init__.py +62 -0
  50. m365-0.1.0a1/src/m365/graph/preprocessing/deduping.py +166 -0
  51. m365-0.1.0a1/src/m365/graph/preprocessing/filters.py +379 -0
  52. m365-0.1.0a1/src/m365/graph/preprocessing/lists.py +319 -0
  53. m365-0.1.0a1/src/m365/graph/preprocessing/structures.py +186 -0
  54. m365-0.1.0a1/src/m365/graph/preprocessing/transforms.py +194 -0
  55. m365-0.1.0a1/src/m365/graph/sharepoint.py +884 -0
  56. m365-0.1.0a1/src/m365/graph/syslib/__init__.py +101 -0
  57. m365-0.1.0a1/src/m365/graph/syslib/_appdata.py +340 -0
  58. m365-0.1.0a1/src/m365/graph/syslib/_loc.py +84 -0
  59. m365-0.1.0a1/src/m365/graph/syslib/_paradigm.py +124 -0
  60. m365-0.1.0a1/src/m365/graph/syslib/_unix.py +184 -0
  61. m365-0.1.0a1/src/m365/graph/syslib/_utils.py +79 -0
  62. m365-0.1.0a1/src/m365/graph/syslib/_windows.py +545 -0
  63. m365-0.1.0a1/src/m365/graph/syslib/base.py +1840 -0
  64. m365-0.1.0a1/src/m365/graph/syslib/ref_data/__init__.py +54 -0
  65. m365-0.1.0a1/src/m365/graph/syslib/ref_data/extensions.txt +924 -0
  66. m365-0.1.0a1/src/m365/graph/utils.py +69 -0
  67. m365-0.1.0a1/src/m365.egg-info/PKG-INFO +132 -0
  68. m365-0.1.0a1/src/m365.egg-info/SOURCES.txt +88 -0
  69. m365-0.1.0a1/src/m365.egg-info/dependency_links.txt +1 -0
  70. m365-0.1.0a1/src/m365.egg-info/requires.txt +9 -0
  71. m365-0.1.0a1/src/m365.egg-info/top_level.txt +1 -0
  72. m365-0.1.0a1/tests/combined/test_namespaces.py +155 -0
  73. m365-0.1.0a1/tests/graph/test_adversarial_330.py +294 -0
  74. m365-0.1.0a1/tests/graph/test_correctness_release.py +310 -0
  75. m365-0.1.0a1/tests/graph/test_dateplumb_advanced.py +298 -0
  76. m365-0.1.0a1/tests/graph/test_dateplumb_core.py +158 -0
  77. m365-0.1.0a1/tests/graph/test_mail_correctness_320.py +391 -0
  78. m365-0.1.0a1/tests/graph/test_packaged_assets.py +128 -0
  79. m365-0.1.0a1/tests/graph/test_path_regressions.py +154 -0
  80. m365-0.1.0a1/tests/graph/test_query_hardening.py +390 -0
  81. m365-0.1.0a1/tests/graph/test_required_auth.py +169 -0
  82. m365-0.1.0a1/tests/graph/test_sharepoint.py +572 -0
  83. m365-0.1.0a1/tests/graph/test_sharepoint_310.py +402 -0
  84. m365-0.1.0a1/tests/graph/test_transfer_hardening.py +388 -0
  85. m365-0.1.0a1/tools/test_suite.py +48 -0
m365-0.1.0a1/GRAPH.md ADDED
@@ -0,0 +1,389 @@
1
+ # m365.graph 3.3.1
2
+
3
+ Reusable Microsoft Graph clients. This correctness release changes the SharePoint
4
+ client locally; it neither provisions tenants nor changes any tenant permissions.
5
+
6
+ ## Install
7
+
8
+ Install the wheel in your application's own Python 3.10+ environment:
9
+
10
+ ~~~powershell
11
+ python -m pip install "C:\path\to\m365-0.1.0a1-py3-none-any.whl"
12
+ ~~~
13
+
14
+ Core dependencies: azauthlib (6.0.6 or newer within 6.x), requests, numpy, and
15
+ tqdm. The built-in authentication factories use azauthlib. It is installed
16
+ automatically; existing
17
+ install commands with `[auth]` still work but no longer change what is installed.
18
+ Factories try silent delegated sign-in by default. If no usable cached sign-in
19
+ exists, they raise `azauthlib.InteractionRequiredError` rather than launching a
20
+ browser. Choose device-code sign-in explicitly or supply an authenticated provider.
21
+
22
+ Applications can still supply a provider whose `access_token` property returns
23
+ a current Graph token. For unattended jobs, use an application/certificate
24
+ provider that does not fall back to interactive login. Use separate provider
25
+ configuration for each organization and tokens for the configured Graph
26
+ audience. Tenant configuration, credentials, grants, and schedules remain the
27
+ deploying organization's responsibility.
28
+
29
+ ## Native Windows certificate authentication
30
+
31
+ Use this app-only flow on Windows with an existing Microsoft Entra application.
32
+ The certificate's **public** half must already be registered on that application,
33
+ and the app must already have access to the exact site or OneDrive resource.
34
+ Use the narrowest existing grant that supports the intended operation. The
35
+ examples below issue read-only requests; they do not grant access.
36
+
37
+ The certificate and its RSA-PSS-capable CNG private key must be in the Windows
38
+ Personal (`My`) store. `CurrentUser` uses the store of the account running
39
+ Python. If the certificate is already in `LocalMachine\My`, pass
40
+ `store_location="LocalMachine"` and run under an account that already has
41
+ permission to use the key. The key can be non-exportable. No PFX export or
42
+ client secret is needed.
43
+
44
+ Set `GRAPH_CLIENT_ID`, `GRAPH_TENANT_ID`, and
45
+ `GRAPH_CERTIFICATE_THUMBPRINT` in your application environment. These are
46
+ identifiers, not credentials. Then run this setup followed by either example:
47
+
48
+ ~~~python
49
+ import os
50
+ from urllib.parse import quote
51
+
52
+ from azauthlib import Authentication
53
+
54
+ auth = Authentication(scopes=["https://graph.microsoft.com/.default"])
55
+ auth.Build.WithWindowsCertificate(
56
+ client_id=os.environ["GRAPH_CLIENT_ID"],
57
+ tenant_id=os.environ["GRAPH_TENANT_ID"],
58
+ thumbprint=os.environ["GRAPH_CERTIFICATE_THUMBPRINT"],
59
+ store_location="CurrentUser",
60
+ )
61
+ auth.ClientCredentials()
62
+ ~~~
63
+
64
+ `ClientCredentials()` selects app-only authentication. Do not use the silent
65
+ delegated sign-in factories for this flow. Reuse the same `auth` object so it
66
+ can supply and renew tokens. Leave encrypted token caching enabled; if you set
67
+ an explicit `token_path`, use a private location specific to that app and tenant.
68
+ Do not log access tokens or signed client assertions.
69
+
70
+ ### SharePoint: read from a selected site
71
+
72
+ Set `GRAPH_SITE_ID` to the complete site ID returned by Microsoft Graph. The
73
+ example uses the site's default document library; pass an authorized
74
+ `drive_id` to `Site` to select a different library.
75
+
76
+ ~~~python
77
+ from m365.graph import Site
78
+
79
+ with Site(token_engine=auth, site_id=os.environ["GRAPH_SITE_ID"]) as site:
80
+ drive = quote(site.drive_id, safe="")
81
+ page = site.api.graph_call(resource_url=f"drives/{drive}/root/children?$top=5")
82
+ for item in page["value"]:
83
+ print(item["name"])
84
+ ~~~
85
+
86
+ ### OneDrive for Business: read from an approved folder
87
+
88
+ OneDrive uses the shared Graph transport; there is no separate high-level
89
+ `OneDrive` client. Set `GRAPH_ONEDRIVE_DRIVE_ID` and
90
+ `GRAPH_ONEDRIVE_FOLDER_ID` to the Graph IDs of the approved drive and folder.
91
+ Use those IDs instead of `/me/drive`, which requires a delegated user token.
92
+ If access is limited to a folder, do not enumerate the drive root.
93
+
94
+ ~~~python
95
+ from types import SimpleNamespace
96
+
97
+ from m365.graph._graph import GraphAPI
98
+
99
+ drive_id = os.environ["GRAPH_ONEDRIVE_DRIVE_ID"]
100
+ folder_id = os.environ["GRAPH_ONEDRIVE_FOLDER_ID"]
101
+ client = SimpleNamespace(
102
+ graph_url="https://graph.microsoft.com/v1.0",
103
+ request_timeout=(10, 30),
104
+ max_retries=2,
105
+ get_token=lambda: auth.access_token,
106
+ )
107
+ resource = f"drives/{quote(drive_id, safe='')}/items/{quote(folder_id, safe='')}"
108
+ api = GraphAPI(client)
109
+ try:
110
+ folder = api.graph_call(resource_url=resource)
111
+ if (folder.get("id") != folder_id
112
+ or folder.get("parentReference", {}).get("driveId") != drive_id
113
+ or not isinstance(folder.get("folder"), dict)
114
+ or "remoteItem" in folder or "deleted" in folder):
115
+ raise ValueError("Graph did not return the configured OneDrive folder")
116
+ page = api.graph_call(resource_url=f"{resource}/children?$top=5")
117
+ for item in page["value"]:
118
+ print(item["name"])
119
+ finally:
120
+ api.close()
121
+ ~~~
122
+
123
+ Both examples read only the first page. If authentication fails, check the
124
+ certificate's store, key access, validity, and Entra registration. If a token
125
+ is issued but Graph returns `403`, check the specific resource grant; a valid
126
+ token does not by itself authorize a site or folder.
127
+
128
+ ## SharePoint example
129
+
130
+ ~~~python
131
+ from m365.graph import Site, GraphError
132
+
133
+ # provider is YOUR token provider; do not put tokens or private keys in source.
134
+ with Site(
135
+ token_engine=provider,
136
+ site_name="https://example.sharepoint.com/teams/Operations",
137
+ drive_name="Contracts",
138
+ request_timeout=(10, 120),
139
+ max_retries=3,
140
+ search_mode="enumerate", # no indexed-search permission required
141
+ search_root=None, # optional item ID for subtree-only name lookup
142
+ ) as site:
143
+ result = site.operations.Uploader(
144
+ r"C:\Exports\report.pdf",
145
+ sharepoint_folder_path="Reports",
146
+ conflict_behavior="fail", # fail (default), replace, or rename
147
+ )
148
+ print(result["id"])
149
+
150
+ files = site.search_by.filename("Reports/report.pdf")
151
+ downloaded = site.operations.Downloader(
152
+ preserve_dir_structure=True
153
+ ).file(r"C:\Downloads\Reports", files)
154
+ ~~~
155
+
156
+ The example identifiers/paths are placeholders, not company defaults.
157
+
158
+ Site addressing accepts a clean HTTPS site URL (including /teams or /sites),
159
+ a hostname/path, or site_id= with Graph's COMPLETE opaque site ID. An optional
160
+ drive_id= must resolve within that site. A named library is searched across all
161
+ pages; otherwise the site's actual default drive is requested. A short site name
162
+ without hostname= discovers the provider's tenant root first (extra read needed).
163
+
164
+ All transfer/search paths are **unencoded and relative to the selected library**.
165
+ Use forward slashes. A subfolder named Documents remains a real subfolder: it is
166
+ not silently stripped. Parent folders must already exist. Absolute URLs are only
167
+ converted when they lie within the selected library's returned webUrl.
168
+
169
+ The selected site's standard /_layouts/15/Doc.aspx?sourcedoc=<GUID> browser
170
+ URLs are also accepted. Their GUID must uniquely match sharepointIds.listItemUniqueId
171
+ in the selected drive; a file= display name is never used as identity proof.
172
+ This uses bounded library metadata traversal, not sharing-link redemption, indexed
173
+ search, or another site's access. Unknown/ambiguous GUIDs and contradictory names
174
+ fail closed. The same traversal budgets apply, so prefer paths/IDs when known.
175
+
176
+ ## Name lookup without broader tenant permissions
177
+
178
+ Bare-name lookup now defaults to bounded child enumeration, not Microsoft's
179
+ indexed drive search. It compares filenames only (case-insensitive exact match,
180
+ or substring when exact_match=False); it does not search document contents.
181
+ search_root= can restrict enumeration to a folder item ID. It does not change
182
+ the meaning of explicit paths, which remain library-relative.
183
+
184
+ Default limits: search_max_items=5000, search_max_requests=200 logical pages,
185
+ search_max_depth=30. Budgets cover the whole traversal; hitting a limit, a cycle,
186
+ an access error or malformed data raises GraphError rather than returning partial
187
+ results or incorrectly declaring a unique match. Remote shortcuts are not followed.
188
+ Duplicate names across folders remain ambiguous. Transport retries are separately
189
+ bounded by max_retries. For large libraries, set a narrow search_root or use paths.
190
+
191
+ search_mode="indexed" remains an explicit opt-in for organizations with compatible
192
+ grants. The client never broadens consent or silently retries with wider access.
193
+
194
+ ## Mailbox safety changes in 2.1.0
195
+
196
+ Mailbox uses the same isolated Graph/capability transport as SharePoint, while
197
+ retaining immutable-ID/body-format preferences. Ordinary JSON HTTP failures retain
198
+ the legacy {"error": ...} result, now redacted; stream and preauthenticated transfer
199
+ failures raise GraphError. Unsupported off-Graph URLs are rejected before token
200
+ use. Attachment upload-session PUTs explicitly use preauthenticated=True.
201
+
202
+ Attachment downloads reject unsafe filenames and existing local destinations,
203
+ stage complete streams, validate size when supplied, close responses, and publish
204
+ without overwriting. Hard-link filesystem support is required as for SharePoint.
205
+ This release does not claim to implement resumable Outlook attachment uploads or
206
+ certify all mailbox endpoints; mailbox validation remained offline/mock only.
207
+
208
+ ## Mailbox read safety in 3.2.0
209
+
210
+ High-level message/folder/attachment reads and delta helpers now raise GraphError
211
+ on request failures or malformed pages instead of returning an apparently complete
212
+ partial/empty result. A 410 delta error has code delta_resync_required: discard
213
+ the invalid sync token only through the caller's explicit resync workflow.
214
+ The library does not delete or reconcile local records automatically.
215
+
216
+ Repeated nextLinks raise pagination_cycle; a default 200-logical-page safety
217
+ budget raises mailbox_page_limit. Explicit page_limit still requests an intentional
218
+ subset. Folder traversal also rejects cycles, depth over 30 and more than 5,000
219
+ folders. These are per-operation safety limits, not broader permission grants.
220
+ Transport retries are separately bounded. Normal repeated delta events remain
221
+ valid. Opaque continuation links are not rebuilt.
222
+
223
+ Name-based folder/attachment resolution must be unique; use an exact ID when
224
+ names collide. Hidden-folder flags reach attached child-folder reads. A string
225
+ select is one field, not a list of characters, and resource IDs are encoded as
226
+ opaque path segments across message, folder and attachment operations.
227
+
228
+ Raw Mailbox.api.graph_call retains its legacy redacted error dictionary for
229
+ ordinary calls, with additive status_code/code fields. Stream, capability and
230
+ response_metadata calls raise failures. High-level reads are deliberately stricter.
231
+ Catch GraphError in code that previously interpreted a failed read as an empty list.
232
+
233
+ Large attachment uploads validate intermediate offsets and final HTTP 201
234
+ completion, including the documented empty final body. For an empty commit body,
235
+ the result is completed=True, status_code=201 and size=<uploaded bytes>; no
236
+ attachment ID is invented. A response with real attachment metadata is preserved.
237
+ Lost PUT responses are not blindly replayed; resumable Outlook upload recovery
238
+ remains outside this release. Only Graph-provided upload capability URLs are used.
239
+ The opt-in response_metadata transport option returns status_code/body, never
240
+ headers or a signed Location URL. It cannot be combined with streaming or batches.
241
+
242
+ SharePoint move results must confirm item ID, filename and destination parent
243
+ (and drive when supplied). A failed confirmation after PATCH does not imply the
244
+ server undid the move: inspect the item's current state before deciding to retry.
245
+
246
+ The preprocessing date_key_extrema helper compares UTC instants without formatting
247
+ away timezone offsets or rewriting original values. from_format is an input
248
+ format. Naive timestamps are UTC by default; callers can pass naive_timezone=
249
+ with a real timezone object. Invalid/missing dates remain excluded. Unordered
250
+ multi-item sets in ensure_single_item are ambiguous and raise; singleton/empty
251
+ sets work, while ordered sequence behavior is retained.
252
+
253
+ ## Adversarial response validation in 3.3.0
254
+
255
+ A present but malformed nextLink now raises instead of silently ending a scan.
256
+ Drive-child continuations remain opaque and must retain the selected explicit
257
+ drive. Supplied parent-drive metadata is checked in collection and search paths.
258
+ Shortcuts are not followed as local selected-drive path matches.
259
+
260
+ Completed SharePoint uploads require a nonempty string ID, integer size, valid
261
+ name and file facet. Contradictory parent drive/path and folder/remote/deleted
262
+ facets fail. Supplied destination metadata is checked; missing parent metadata
263
+ is not invented and this is not independent destination readback or hash proof.
264
+ The rename conflict policy permits a valid server-renamed filename; fail/replace
265
+ require the requested name (case-insensitive). A validation error after commit
266
+ does NOT undo the server upload: inspect the destination before retrying.
267
+
268
+ Upload ranges require complete valid byte-range syntax and bounds; multiple
269
+ missing ranges remain supported. Batch statuses must be valid integer final
270
+ HTTP statuses; non-2xx responses raise redacted GraphError. Redirect subresponses
271
+ raise batch_subrequest_redirect and are never implicitly followed or replayed.
272
+
273
+ Downloads stop at the first chunk exceeding a supplied nonnegative integer size,
274
+ before writing that chunk. Final size checks, cleanup and atomic no-overwrite
275
+ publication remain. An unspecified size has no new implicit maximum. Windows
276
+ reserved COM/LPT superscript-digit forms are rejected before local I/O.
277
+ Outlook upload error bodies cannot masquerade as successful 201 completion;
278
+ documented empty 201 completion remains supported.
279
+
280
+ ## Correctness and failure semantics
281
+
282
+ - Nonempty files and BytesIO use sequential upload sessions with explicit conflict
283
+ policy. For BytesIO, provide new_file_name=. Caller stream position is restored.
284
+ - On a lost upload acknowledgement, query session state before resuming. A lost
285
+ final response whose outcome cannot be established raises
286
+ GraphError(code="upload_completion_unknown"); inspect the destination before retry.
287
+ - Uploads return completed Graph item metadata with validated size, not raw bytes.
288
+ This is not an end-to-end content-hash verification guarantee.
289
+ - Downloads consume every nextLink page. Failed downloads raise and clean temporary
290
+ files; complete files from the same failed batch may remain. A batch/tree is not
291
+ transactional. Existing local files are never overwritten.
292
+ - ZIP compression includes only this call's downloaded files and retains originals.
293
+ Folder downloads also retain encountered empty-directory entries (including a
294
+ wholly empty root). Structured archives retain their relative directory names;
295
+ flat archives reject colliding names rather than losing directories or files.
296
+ Flat-name collisions fail explicitly. Atomic no-clobber file/ZIP publication uses
297
+ hard links; unsupported filesystems fail rather than falling back to overwrite.
298
+ - Drive-child collection queries with an explicit non-name ordering add name asc
299
+ as a deterministic tie-break on the initial request. An explicit projection also
300
+ includes id for duplicate validation. Subsequent nextLinks remain opaque and
301
+ unchanged. Duplicate/missing IDs raise rather than silently deduplicating or
302
+ restarting. All collections bind continuation paths to the original endpoint;
303
+ delta collections still preserve repeated events and tombstones.
304
+ Iterators may have yielded earlier pages before a later error; consume them
305
+ successfully before committing completeness-dependent work. This is not a
306
+ snapshot-isolation guarantee during concurrent library changes, nor a claim
307
+ that Microsoft supports every orderby field.
308
+ - Windows transfers use filesystem extended paths internally for local drive/UNC
309
+ paths, without changing registry/group policy. Short returned paths remain
310
+ ordinary Paths; long returned paths keep their extended prefix so callers can
311
+ read them in the same environment. OS/filesystem component limits still apply.
312
+ - File counts, download workers, upload fragment sizes and batch sizes reject
313
+ booleans/non-integers before requests instead of treating True as 1.
314
+ - Transport errors raise GraphError; status_code and code are available. Errors
315
+ exclude response bodies, bearer tokens, and preauthenticated URL values.
316
+ - Arbitrary external URLs are rejected by normal graph_call. Only Graph-provided
317
+ capability URLs should be passed with preauthenticated=True. They use a separate
318
+ session and never receive the Graph bearer.
319
+ - Read/throttle retries are bounded. Mutations with ambiguous transport outcomes
320
+ are not blindly replayed. Batch subrequest failures raise and are not hidden.
321
+ - Retargeting site_name/drive_name is validated atomically and rolls back on failure.
322
+ Do not retarget a client while its transfers are running.
323
+ - Optional graph_url= supports explicit Graph cloud endpoints; the provider must
324
+ use that endpoint's audience. No cloud configuration is auto-detected.
325
+ - Legacy GET-cache arguments remain accepted but transport caching is disabled.
326
+
327
+ ## Deliberate boundaries
328
+
329
+ The uploader does not silently traverse directories, ZIP them, exclude files,
330
+ or choose archive locations. Enumerate/archive a directory explicitly in your
331
+ application. Empty files fail before HTTP because the session fragment protocol
332
+ cannot safely represent them with the implemented conflict guarantees.
333
+
334
+ This release does not add a personal-OneDrive client, access live mailboxes,
335
+ configure certificates, or change the existing sharepoint-upload Windows command.
336
+ There are no company-specific archive names, tenant IDs, or deployment paths.
337
+
338
+ ## Internal utilities
339
+
340
+ ~~~python
341
+ from m365.graph import syslib, dateplumb
342
+
343
+ size = syslib.Buffer.convert_size("4MB")
344
+ parsed = dateplumb.parse("2026-11-17")
345
+ ~~~
346
+
347
+ These are packaged as m365.graph.syslib and m365.graph.dateplumb. Do not install or
348
+ alias global syslib/dateplumb packages for this client. Core Graph timestamp
349
+ parsing, dateplumb.parse/quick_parse and timestamp sorting do not require dately.
350
+ They do not silently fall back to advanced date parsing.
351
+
352
+ Advanced methods pro_parse/conversion, detect, fragment, sequence and sub.date
353
+ require the optional dates extra:
354
+
355
+ ~~~powershell
356
+ python -m pip install "m365[dates]"
357
+ # For the local release artifact:
358
+ python -m pip install "C:\path\to\m365-0.1.0a1-py3-none-any.whl[dates]"
359
+ ~~~
360
+
361
+ Missing or unsupported backends raise an actionable ImportError when an advanced
362
+ method is called, not during package import. The supported stable range is
363
+ dately>=4.7.8,<4.8; 4.7.8 is integration-tested. Applications should lock the exact
364
+ tested version. Dately owns general parsing/detection/formatting; a small adapter
365
+ preserves timezone, collection, substitution and transactional-update fixes.
366
+ There is no competing internal general-date parser or automatic fallback.
367
+
368
+ See [date migration contracts](release/DATEPLUMB-3.0.0.md). This is a major release
369
+ because advanced methods no longer work in a core-only installation. Other Dately
370
+ features such as natural-language calendars are not re-exported here.
371
+
372
+ ## Offline validation
373
+
374
+ ~~~powershell
375
+ python -B tools/test_suite.py graph --output <results-directory> --dist <built-distributions>
376
+ python -B tools/test_suite.py combined --output <results-directory> --dist <built-distributions>
377
+ python -m build
378
+ ~~~
379
+
380
+ The regression suite forbids unmocked HTTP. It covers site/drive binding, tenant
381
+ separation, payload fidelity, capability-URL authentication boundaries, pagination,
382
+ retries, uploads/resume, download safety, searches/moves, and internal utilities.
383
+ See CHANGELOG.md for intentional major-version compatibility changes and
384
+ release/VALIDATION-3.0.0.md for the current validation record. Previous release
385
+ validation records are preserved.
386
+
387
+ Reference contracts:
388
+ - [Site by path](https://learn.microsoft.com/en-us/graph/api/site-getbypath?view=graph-rest-1.0)
389
+ - [Upload sessions](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession?view=graph-rest-1.0)
m365-0.1.0a1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 DOYDL Technologies
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,16 @@
1
+ include README.md GRAPH.md LICENSE
2
+ recursive-include assets *.svg *.png *.txt *LICENSE*
3
+ recursive-include tests *.py
4
+ recursive-include tools *.py
5
+ recursive-include src/m365/graph/syslib/ref_data *.txt
6
+ prune comoutlook
7
+ prune m365/outlook_com
8
+ prune src/m365/outlook_com
9
+ prune tests/com
10
+ prune msftgraph
11
+ prune src/comoutlook
12
+ prune src/msftgraph
13
+ prune src/m365/graph/.deprecated
14
+ prune .local
15
+ prune release
16
+ global-exclude *.pyc
m365-0.1.0a1/PKG-INFO ADDED
@@ -0,0 +1,132 @@
1
+ Metadata-Version: 2.4
2
+ Name: m365
3
+ Version: 0.1.0a1
4
+ Summary: Independent Microsoft Graph toolkit for Microsoft 365
5
+ Author: DOYDL Technologies
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/doydl-technologies/m365
8
+ Project-URL: Documentation, https://github.com/doydl-technologies/m365#readme
9
+ Project-URL: Issues, https://github.com/doydl-technologies/m365/issues
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Office/Business
13
+ Requires-Python: >=3.10
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ License-File: assets/third-party/ONEDRIVE-NOTICE.txt
17
+ License-File: assets/third-party/OUTLOOK-NOTICE.txt
18
+ License-File: assets/third-party/SHAREPOINT-NOTICE.txt
19
+ License-File: assets/svg/LOGO-LICENSE
20
+ License-File: assets/png/LOGO-LICENSE
21
+ Requires-Dist: azauthlib<7,>=6.0.6
22
+ Requires-Dist: numpy
23
+ Requires-Dist: requests
24
+ Requires-Dist: tqdm
25
+ Provides-Extra: dates
26
+ Requires-Dist: dately<4.8,>=4.7.8; extra == "dates"
27
+ Provides-Extra: auth
28
+ Dynamic: license-file
29
+ Dynamic: provides-extra
30
+ Dynamic: requires-dist
31
+ Dynamic: requires-python
32
+ Dynamic: summary
33
+
34
+ # m365
35
+
36
+ **An independent Python toolkit for Microsoft 365 through Microsoft Graph.**
37
+
38
+ Version **0.1.0a1** is a functional, experimental, **Graph-only alpha**. It is
39
+ not an official Microsoft package and is not affiliated with or endorsed by
40
+ Microsoft. No classic Outlook COM backend is bundled. Standalone comoutlook
41
+ remains a separate project.
42
+
43
+ ## Installation
44
+
45
+ Requires Python 3.10 or newer. Before public publication, install the local wheel:
46
+
47
+ ```powershell
48
+ python -m pip install ".\dist\m365-0.1.0a1-py3-none-any.whl"
49
+ # Optional advanced date methods:
50
+ python -m pip install ".\dist\m365-0.1.0a1-py3-none-any.whl[dates]"
51
+ ```
52
+
53
+ The distribution name and import package are both `m365`. The local deployment
54
+ folder number is independent of the Python distribution version.
55
+ `azauthlib>=6.0.6,<7` is required in the base install; `[auth]` remains a
56
+ compatibility alias. The `dates` extra is optional. Auth dependencies may bring
57
+ PySide6 and Windows-support components; that does not add an Outlook COM API.
58
+
59
+ Installation grants no permissions, signs into no account, starts no Outlook
60
+ session, and configures no scheduled jobs. The application owns tenant
61
+ selection, credentials, consent, and resource grants.
62
+
63
+ ## Graph namespace
64
+
65
+ The repository uses a `src` layout, consistent with the sibling libraries:
66
+
67
+ ```text
68
+ src/m365/ Python package implementation
69
+ assets/ Branding images and third-party notices
70
+ tests/ Offline regression tests
71
+ tools/test_suite.py Source/installed-package test runner
72
+ ```
73
+
74
+ For local development, run `python -m pip install -e ".[dates]"` from the
75
+ project root. Building also runs from the project root, not from `src`.
76
+ Public imports remain `from m365.graph import Site, Mailbox`.
77
+
78
+ ```python
79
+ from m365.graph import Site, Mailbox, GraphError
80
+
81
+ # provider returns a current Graph token via its access_token property.
82
+ with Site(
83
+ token_engine=provider,
84
+ site_name="https://example.sharepoint.com/sites/Operations",
85
+ ) as site:
86
+ files = site.search_by.filename("Reports/report.pdf")
87
+ ```
88
+
89
+ The client supports SharePoint documents, OneDrive drive transfers, and cloud
90
+ Outlook mailbox workflows. **Outlook mail through Graph is still included**;
91
+ this is different from desktop COM automation. File operations do not require
92
+ mailbox permissions. Each organization configures its own authorized resources.
93
+
94
+ See [the Graph reference](GRAPH.md) for authentication, resource selection,
95
+ uploads, downloads, pagination, and mailbox methods. Never embed private keys
96
+ or bearer tokens in source. For background work, use a configured provider
97
+ that does not silently initiate interactive login.
98
+
99
+ ## Alpha compatibility
100
+
101
+ Use `m365.graph`. This distribution installs no `msftgraph` compatibility
102
+ package, `comoutlook` package, or `m365.outlook_com` namespace. Existing
103
+ standalone projects are not removed by installing it.
104
+
105
+ The Graph backend retains its implementation version identifier. Use
106
+ `m365.__version__` for the distribution's alpha version.
107
+
108
+ ## Offline tests and builds
109
+
110
+ ```powershell
111
+ python tools/test_suite.py graph --output .local/tests/graph
112
+ python tools/test_suite.py combined --output .local/tests/namespace
113
+ python -m build
114
+ ```
115
+
116
+ Add `--dist dist` after building to validate artifacts. The `combined` suite
117
+ name is retained for the root-namespace and packaging checks; it does not imply
118
+ a bundled COM backend. Tests use synthetic responses and local fixtures,
119
+ not live mail or tenant resources.
120
+
121
+ ## License and notices
122
+
123
+ MIT. Third-party notices under `assets/third-party` are preserved.
124
+ Those notices do not license Microsoft's trademarks or logos. The original
125
+ m365 logo in `assets` has its own MIT notice. Microsoft, Microsoft 365,
126
+ Microsoft Graph, Outlook, SharePoint, and OneDrive are trademarks of their
127
+ respective owner. The project name describes interoperability, not affiliation.
128
+
129
+ Root branding images are included in the source distribution. They are not
130
+ runtime resources and are not copied into the installed Python package.
131
+ Relevant license and attribution files are retained in the wheel's license
132
+ metadata. The library's runtime extension data remains package data under `src`.
m365-0.1.0a1/README.md ADDED
@@ -0,0 +1,99 @@
1
+ # m365
2
+
3
+ **An independent Python toolkit for Microsoft 365 through Microsoft Graph.**
4
+
5
+ Version **0.1.0a1** is a functional, experimental, **Graph-only alpha**. It is
6
+ not an official Microsoft package and is not affiliated with or endorsed by
7
+ Microsoft. No classic Outlook COM backend is bundled. Standalone comoutlook
8
+ remains a separate project.
9
+
10
+ ## Installation
11
+
12
+ Requires Python 3.10 or newer. Before public publication, install the local wheel:
13
+
14
+ ```powershell
15
+ python -m pip install ".\dist\m365-0.1.0a1-py3-none-any.whl"
16
+ # Optional advanced date methods:
17
+ python -m pip install ".\dist\m365-0.1.0a1-py3-none-any.whl[dates]"
18
+ ```
19
+
20
+ The distribution name and import package are both `m365`. The local deployment
21
+ folder number is independent of the Python distribution version.
22
+ `azauthlib>=6.0.6,<7` is required in the base install; `[auth]` remains a
23
+ compatibility alias. The `dates` extra is optional. Auth dependencies may bring
24
+ PySide6 and Windows-support components; that does not add an Outlook COM API.
25
+
26
+ Installation grants no permissions, signs into no account, starts no Outlook
27
+ session, and configures no scheduled jobs. The application owns tenant
28
+ selection, credentials, consent, and resource grants.
29
+
30
+ ## Graph namespace
31
+
32
+ The repository uses a `src` layout, consistent with the sibling libraries:
33
+
34
+ ```text
35
+ src/m365/ Python package implementation
36
+ assets/ Branding images and third-party notices
37
+ tests/ Offline regression tests
38
+ tools/test_suite.py Source/installed-package test runner
39
+ ```
40
+
41
+ For local development, run `python -m pip install -e ".[dates]"` from the
42
+ project root. Building also runs from the project root, not from `src`.
43
+ Public imports remain `from m365.graph import Site, Mailbox`.
44
+
45
+ ```python
46
+ from m365.graph import Site, Mailbox, GraphError
47
+
48
+ # provider returns a current Graph token via its access_token property.
49
+ with Site(
50
+ token_engine=provider,
51
+ site_name="https://example.sharepoint.com/sites/Operations",
52
+ ) as site:
53
+ files = site.search_by.filename("Reports/report.pdf")
54
+ ```
55
+
56
+ The client supports SharePoint documents, OneDrive drive transfers, and cloud
57
+ Outlook mailbox workflows. **Outlook mail through Graph is still included**;
58
+ this is different from desktop COM automation. File operations do not require
59
+ mailbox permissions. Each organization configures its own authorized resources.
60
+
61
+ See [the Graph reference](GRAPH.md) for authentication, resource selection,
62
+ uploads, downloads, pagination, and mailbox methods. Never embed private keys
63
+ or bearer tokens in source. For background work, use a configured provider
64
+ that does not silently initiate interactive login.
65
+
66
+ ## Alpha compatibility
67
+
68
+ Use `m365.graph`. This distribution installs no `msftgraph` compatibility
69
+ package, `comoutlook` package, or `m365.outlook_com` namespace. Existing
70
+ standalone projects are not removed by installing it.
71
+
72
+ The Graph backend retains its implementation version identifier. Use
73
+ `m365.__version__` for the distribution's alpha version.
74
+
75
+ ## Offline tests and builds
76
+
77
+ ```powershell
78
+ python tools/test_suite.py graph --output .local/tests/graph
79
+ python tools/test_suite.py combined --output .local/tests/namespace
80
+ python -m build
81
+ ```
82
+
83
+ Add `--dist dist` after building to validate artifacts. The `combined` suite
84
+ name is retained for the root-namespace and packaging checks; it does not imply
85
+ a bundled COM backend. Tests use synthetic responses and local fixtures,
86
+ not live mail or tenant resources.
87
+
88
+ ## License and notices
89
+
90
+ MIT. Third-party notices under `assets/third-party` are preserved.
91
+ Those notices do not license Microsoft's trademarks or logos. The original
92
+ m365 logo in `assets` has its own MIT notice. Microsoft, Microsoft 365,
93
+ Microsoft Graph, Outlook, SharePoint, and OneDrive are trademarks of their
94
+ respective owner. The project name describes interoperability, not affiliation.
95
+
96
+ Root branding images are included in the source distribution. They are not
97
+ runtime resources and are not copied into the installed Python package.
98
+ Relevant license and attribution files are retained in the wheel's license
99
+ metadata. The library's runtime extension data remains package data under `src`.