0
# File Storage and Drive Management
1

2
OneDrive and SharePoint file operations including upload, download, sharing, versioning, and folder management with support for large file transfers and permissions.
3

4
## Capabilities
5

6
### Storage Access
7

8
Access file storage services including OneDrive and SharePoint document libraries.
9

10
```python { .api }
11
def storage(self, resource: str = None) -> Storage:
12
    """
13
    Get a storage instance for file operations.
14
    
15
    Parameters:
16
    - resource: user resource identifier (defaults to authenticated user)
17
    
18
    Returns:
19
    - Storage: Storage instance for file operations
20
    """
21

22
class Storage:
23
    def __init__(self, parent: Account, main_resource: str = None): ...
24
    
25
    def get_default_drive(self) -> Drive:
26
        """Get the user's default OneDrive."""
27
    
28
    def get_drives(self, limit: int = None) -> list[Drive]:
29
        """
30
        Get all accessible drives.
31
        
32
        Parameters:
33
        - limit: maximum number of drives to return
34
        
35
        Returns:
36
        - list[Drive]: List of drive objects
37
        """
38
    
39
    def get_drive(self, drive_id: str) -> Drive:
40
        """
41
        Get a specific drive by ID.
42
        
43
        Parameters:
44
        - drive_id: drive identifier
45
        
46
        Returns:
47
        - Drive: Drive object
48
        """
49
```
50

51
### Drive Operations
52

53
Manage drives and their contents including folders and files.
54

55
```python { .api }
56
class Drive:
57
    @property
58
    def name(self) -> str:
59
        """Drive display name."""
60
    
61
    @property
62
    def drive_type(self) -> str:
63
        """Drive type (personal, business, documentLibrary)."""
64
    
65
    @property
66
    def owner(self) -> str:
67
        """Drive owner information."""
68
    
69
    @property
70
    def quota(self) -> dict:
71
        """Drive quota information (total, used, remaining)."""
72
    
73
    def get_root_folder(self) -> Folder:
74
        """Get the root folder of this drive."""
75
    
76
    def get_items(self, limit: int = None, **filters) -> list[DriveItem]:
77
        """
78
        Get items from this drive.
79
        
80
        Parameters:
81
        - limit: maximum number of items to return
82
        - filters: OData query filters
83
        
84
        Returns:
85
        - list[DriveItem]: List of drive items
86
        """
87
    
88
    def get_item(self, item_id: str = None, item_path: str = None) -> DriveItem:
89
        """
90
        Get a specific item by ID or path.
91
        
92
        Parameters:
93
        - item_id: item identifier
94
        - item_path: item path from drive root
95
        
96
        Returns:
97
        - DriveItem: Drive item object
98
        """
99
```
100

101
### File and Folder Management
102

103
Create, upload, download, and manage files and folders.
104

105
```python { .api }
106
class DriveItem:
107
    @property
108
    def name(self) -> str:
109
        """Item name."""
110
    
111
    @property
112
    def size(self) -> int:
113
        """Item size in bytes."""
114
    
115
    @property
116
    def created_time(self) -> datetime:
117
        """When the item was created."""
118
    
119
    @property
120
    def modified_time(self) -> datetime:
121
        """When the item was last modified."""
122
    
123
    @property
124
    def is_file(self) -> bool:
125
        """Whether this item is a file."""
126
    
127
    @property
128
    def is_folder(self) -> bool:
129
        """Whether this item is a folder."""
130
    
131
    @property
132
    def mime_type(self) -> str:
133
        """MIME type for files."""
134
    
135
    @property
136
    def web_url(self) -> str:
137
        """Web URL to view/edit the item."""
138
    
139
    def download(self, to_path: str = None, chunk_size: int = 1024*1024) -> str:
140
        """
141
        Download the file.
142
        
143
        Parameters:
144
        - to_path: local path to save the file
145
        - chunk_size: download chunk size in bytes
146
        
147
        Returns:
148
        - str: path to downloaded file
149
        """
150
    
151
    def upload(self, file_path: str = None, file_content: bytes = None,
152
               chunk_size: int = 1024*1024) -> bool:
153
        """
154
        Upload content to this item.
155
        
156
        Parameters:
157
        - file_path: path to file to upload
158
        - file_content: file content as bytes
159
        - chunk_size: upload chunk size in bytes
160
        
161
        Returns:
162
        - bool: True if successful
163
        """
164
    
165
    def delete(self) -> bool:
166
        """Delete this item."""
167
    
168
    def copy_to(self, target_folder: 'DriveItem', new_name: str = None) -> 'DriveItem':
169
        """
170
        Copy this item to another folder.
171
        
172
        Parameters:
173
        - target_folder: destination folder
174
        - new_name: new name for the copied item
175
        
176
        Returns:
177
        - DriveItem: The copied item
178
        """
179
    
180
    def move_to(self, target_folder: 'DriveItem', new_name: str = None) -> bool:
181
        """
182
        Move this item to another folder.
183
        
184
        Parameters:
185
        - target_folder: destination folder
186
        - new_name: new name for the moved item
187
        
188
        Returns:
189
        - bool: True if successful
190
        """
191

192
class Folder(DriveItem):
193
    def get_items(self, limit: int = None) -> list[DriveItem]:
194
        """Get items in this folder."""
195
    
196
    def create_folder(self, folder_name: str) -> 'Folder':
197
        """
198
        Create a subfolder.
199
        
200
        Parameters:
201
        - folder_name: name for the new folder
202
        
203
        Returns:
204
        - Folder: Created folder object
205
        """
206
    
207
    def upload_file(self, file_path: str, new_name: str = None) -> File:
208
        """
209
        Upload a file to this folder.
210
        
211
        Parameters:
212
        - file_path: path to file to upload
213
        - new_name: new name for the uploaded file
214
        
215
        Returns:
216
        - File: Uploaded file object
217
        """
218

219
class File(DriveItem):
220
    @property
221
    def content(self) -> bytes:
222
        """File content as bytes."""
223
    
224
    def get_versions(self) -> list['FileVersion']:
225
        """Get file version history."""
226
    
227
    def create_sharing_link(self, link_type: str = 'view', 
228
                           scope: str = 'anonymous') -> dict:
229
        """
230
        Create a sharing link for this file.
231
        
232
        Parameters:
233
        - link_type: 'view' or 'edit'
234
        - scope: 'anonymous', 'organization', or 'users'
235
        
236
        Returns:
237
        - dict: Sharing link information
238
        """
239
```
240

241
### Sharing and Permissions
242

243
Manage file and folder sharing with permission control.
244

245
```python { .api }
246
def get_permissions(self) -> list[Permission]:
247
    """Get current permissions on this item."""
248

249
def create_sharing_link(self, link_type: str = 'view', scope: str = 'anonymous',
250
                       password: str = None, expiration_date: datetime = None) -> dict:
251
    """
252
    Create a sharing link.
253
    
254
    Parameters:
255
    - link_type: 'view', 'edit', or 'embed'
256
    - scope: 'anonymous', 'organization', or 'users'
257
    - password: optional password protection
258
    - expiration_date: optional expiration date
259
    
260
    Returns:
261
    - dict: Sharing link with URL and permissions
262
    """
263

264
def invite_users(self, recipients: list[str], role: str = 'read',
265
                message: str = None, require_sign_in: bool = True) -> list[Permission]:
266
    """
267
    Invite users to access this item.
268
    
269
    Parameters:
270
    - recipients: list of email addresses
271
    - role: 'read', 'write', or 'owner'
272
    - message: optional invitation message
273
    - require_sign_in: whether sign-in is required
274
    
275
    Returns:
276
    - list[Permission]: Created permissions
277
    """
278

279
class Permission:
280
    @property
281
    def id(self) -> str:
282
        """Permission ID."""
283
    
284
    @property
285
    def role(self) -> str:
286
        """Permission role (read, write, owner)."""
287
    
288
    @property
289
    def granted_to(self) -> dict:
290
        """Information about who has this permission."""
291
    
292
    @property
293
    def link(self) -> dict:
294
        """Sharing link information if applicable."""
295
    
296
    def delete(self) -> bool:
297
        """Remove this permission."""
298
```
299

300
### Search Operations
301

302
Search for files and folders across drives.
303

304
```python { .api }
305
def search(self, query: str, limit: int = None) -> list[DriveItem]:
306
    """
307
    Search for items in this drive.
308
    
309
    Parameters:
310
    - query: search query text
311
    - limit: maximum number of results
312
    
313
    Returns:
314
    - list[DriveItem]: Matching items
315
    """
316

317
# Search filters for get_items()
318
# By name: name__contains='document'
319
# By file type: file_extension='pdf'
320
# By modified date: modified_time__gte=datetime(2023, 1, 1)
321
# By size: size__gte=1024*1024  # Files larger than 1MB
322
```
323

324
## Usage Examples
325

326
### Basic File Operations
327

328
```python
329
from O365 import Account
330

331
account = Account(credentials)
332
storage = account.storage()
333
drive = storage.get_default_drive()
334

335
# List files in root folder
336
root_folder = drive.get_root_folder()
337
items = root_folder.get_items()
338

339
for item in items:
340
    if item.is_file:
341
        print(f"File: {item.name} ({item.size} bytes)")
342
    else:
343
        print(f"Folder: {item.name}")
344
```
345

346
### Upload and Download Files
347

348
```python
349
# Upload a file
350
uploaded_file = root_folder.upload_file('/local/path/document.pdf')
351
print(f"Uploaded: {uploaded_file.name}")
352

353
# Download a file
354
local_path = uploaded_file.download('/local/downloads/')
355
print(f"Downloaded to: {local_path}")
356

357
# Upload with progress tracking for large files
358
large_file = root_folder.upload_file(
359
    '/local/path/large_video.mp4',
360
    chunk_size=5*1024*1024  # 5MB chunks
361
)
362
```
363

364
### Folder Management
365

366
```python
367
# Create a project folder structure
368
projects_folder = root_folder.create_folder('Projects')
369
current_project = projects_folder.create_folder('Current Project')
370

371
# Create subfolders
372
docs_folder = current_project.create_folder('Documents')
373
images_folder = current_project.create_folder('Images')
374
archived_folder = current_project.create_folder('Archived')
375

376
# Move files to appropriate folders
377
for item in root_folder.get_items():
378
    if item.is_file and item.name.endswith('.pdf'):
379
        item.move_to(docs_folder)
380
    elif item.is_file and item.name.endswith(('.jpg', '.png', '.gif')):
381
        item.move_to(images_folder)
382
```
383

384
### File Sharing
385

386
```python
387
# Create a public sharing link
388
document = drive.get_item(item_path='/Documents/report.pdf')
389
sharing_link = document.create_sharing_link(
390
    link_type='view',
391
    scope='anonymous'
392
)
393
print(f"Share URL: {sharing_link['web_url']}")
394

395
# Invite specific users with edit permissions
396
document.invite_users(
397
    recipients=['colleague@company.com', 'manager@company.com'],
398
    role='write',
399
    message='Please review and edit this document'
400
)
401

402
# Create password-protected link with expiration
403
from datetime import datetime, timedelta
404

405
secure_link = document.create_sharing_link(
406
    link_type='edit',
407
    scope='organization',
408
    password='SecurePass123',
409
    expiration_date=datetime.now() + timedelta(days=7)
410
)
411
```
412

413
### Search and Filter
414

415
```python
416
# Search for specific files
417
pdf_files = drive.search('type:pdf')
418
recent_files = drive.search('modified:>=2023-01-01')
419

420
# Filter by file properties
421
large_files = root_folder.get_items(
422
    size__gte=10*1024*1024,  # Files larger than 10MB
423
    limit=20
424
)
425

426
# Find files modified in the last week
427
from datetime import datetime, timedelta
428

429
recent = datetime.now() - timedelta(days=7)
430
recent_files = root_folder.get_items(
431
    modified_time__gte=recent
432
)
433

434
for file in recent_files:
435
    print(f"Recently modified: {file.name} - {file.modified_time}")
436
```