File Storage and Drive Management

def storage(self, resource: str = None) -> Storage:
    """
    Get a storage instance for file operations.
    
    Parameters:
    - resource: user resource identifier (defaults to authenticated user)
    
    Returns:
    - Storage: Storage instance for file operations
    """

class Storage:
    def __init__(self, parent: Account, main_resource: str = None): ...
    
    def get_default_drive(self) -> Drive:
        """Get the user's default OneDrive."""
    
    def get_drives(self, limit: int = None) -> list[Drive]:
        """
        Get all accessible drives.
        
        Parameters:
        - limit: maximum number of drives to return
        
        Returns:
        - list[Drive]: List of drive objects
        """
    
    def get_drive(self, drive_id: str) -> Drive:
        """
        Get a specific drive by ID.
        
        Parameters:
        - drive_id: drive identifier
        
        Returns:
        - Drive: Drive object
        """

class Drive:
    @property
    def name(self) -> str:
        """Drive display name."""
    
    @property
    def drive_type(self) -> str:
        """Drive type (personal, business, documentLibrary)."""
    
    @property
    def owner(self) -> str:
        """Drive owner information."""
    
    @property
    def quota(self) -> dict:
        """Drive quota information (total, used, remaining)."""
    
    def get_root_folder(self) -> Folder:
        """Get the root folder of this drive."""
    
    def get_items(self, limit: int = None, **filters) -> list[DriveItem]:
        """
        Get items from this drive.
        
        Parameters:
        - limit: maximum number of items to return
        - filters: OData query filters
        
        Returns:
        - list[DriveItem]: List of drive items
        """
    
    def get_item(self, item_id: str = None, item_path: str = None) -> DriveItem:
        """
        Get a specific item by ID or path.
        
        Parameters:
        - item_id: item identifier
        - item_path: item path from drive root
        
        Returns:
        - DriveItem: Drive item object
        """

class DriveItem:
    @property
    def name(self) -> str:
        """Item name."""
    
    @property
    def size(self) -> int:
        """Item size in bytes."""
    
    @property
    def created_time(self) -> datetime:
        """When the item was created."""
    
    @property
    def modified_time(self) -> datetime:
        """When the item was last modified."""
    
    @property
    def is_file(self) -> bool:
        """Whether this item is a file."""
    
    @property
    def is_folder(self) -> bool:
        """Whether this item is a folder."""
    
    @property
    def mime_type(self) -> str:
        """MIME type for files."""
    
    @property
    def web_url(self) -> str:
        """Web URL to view/edit the item."""
    
    def download(self, to_path: str = None, chunk_size: int = 1024*1024) -> str:
        """
        Download the file.
        
        Parameters:
        - to_path: local path to save the file
        - chunk_size: download chunk size in bytes
        
        Returns:
        - str: path to downloaded file
        """
    
    def upload(self, file_path: str = None, file_content: bytes = None,
               chunk_size: int = 1024*1024) -> bool:
        """
        Upload content to this item.
        
        Parameters:
        - file_path: path to file to upload
        - file_content: file content as bytes
        - chunk_size: upload chunk size in bytes
        
        Returns:
        - bool: True if successful
        """
    
    def delete(self) -> bool:
        """Delete this item."""
    
    def copy_to(self, target_folder: 'DriveItem', new_name: str = None) -> 'DriveItem':
        """
        Copy this item to another folder.
        
        Parameters:
        - target_folder: destination folder
        - new_name: new name for the copied item
        
        Returns:
        - DriveItem: The copied item
        """
    
    def move_to(self, target_folder: 'DriveItem', new_name: str = None) -> bool:
        """
        Move this item to another folder.
        
        Parameters:
        - target_folder: destination folder
        - new_name: new name for the moved item
        
        Returns:
        - bool: True if successful
        """

class Folder(DriveItem):
    def get_items(self, limit: int = None) -> list[DriveItem]:
        """Get items in this folder."""
    
    def create_folder(self, folder_name: str) -> 'Folder':
        """
        Create a subfolder.
        
        Parameters:
        - folder_name: name for the new folder
        
        Returns:
        - Folder: Created folder object
        """
    
    def upload_file(self, file_path: str, new_name: str = None) -> File:
        """
        Upload a file to this folder.
        
        Parameters:
        - file_path: path to file to upload
        - new_name: new name for the uploaded file
        
        Returns:
        - File: Uploaded file object
        """

class File(DriveItem):
    @property
    def content(self) -> bytes:
        """File content as bytes."""
    
    def get_versions(self) -> list['FileVersion']:
        """Get file version history."""
    
    def create_sharing_link(self, link_type: str = 'view', 
                           scope: str = 'anonymous') -> dict:
        """
        Create a sharing link for this file.
        
        Parameters:
        - link_type: 'view' or 'edit'
        - scope: 'anonymous', 'organization', or 'users'
        
        Returns:
        - dict: Sharing link information
        """

def get_permissions(self) -> list[Permission]:
    """Get current permissions on this item."""

def create_sharing_link(self, link_type: str = 'view', scope: str = 'anonymous',
                       password: str = None, expiration_date: datetime = None) -> dict:
    """
    Create a sharing link.
    
    Parameters:
    - link_type: 'view', 'edit', or 'embed'
    - scope: 'anonymous', 'organization', or 'users'
    - password: optional password protection
    - expiration_date: optional expiration date
    
    Returns:
    - dict: Sharing link with URL and permissions
    """

def invite_users(self, recipients: list[str], role: str = 'read',
                message: str = None, require_sign_in: bool = True) -> list[Permission]:
    """
    Invite users to access this item.
    
    Parameters:
    - recipients: list of email addresses
    - role: 'read', 'write', or 'owner'
    - message: optional invitation message
    - require_sign_in: whether sign-in is required
    
    Returns:
    - list[Permission]: Created permissions
    """

class Permission:
    @property
    def id(self) -> str:
        """Permission ID."""
    
    @property
    def role(self) -> str:
        """Permission role (read, write, owner)."""
    
    @property
    def granted_to(self) -> dict:
        """Information about who has this permission."""
    
    @property
    def link(self) -> dict:
        """Sharing link information if applicable."""
    
    def delete(self) -> bool:
        """Remove this permission."""

def search(self, query: str, limit: int = None) -> list[DriveItem]:
    """
    Search for items in this drive.
    
    Parameters:
    - query: search query text
    - limit: maximum number of results
    
    Returns:
    - list[DriveItem]: Matching items
    """

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

from O365 import Account

account = Account(credentials)
storage = account.storage()
drive = storage.get_default_drive()

# List files in root folder
root_folder = drive.get_root_folder()
items = root_folder.get_items()

for item in items:
    if item.is_file:
        print(f"File: {item.name} ({item.size} bytes)")
    else:
        print(f"Folder: {item.name}")

# Upload a file
uploaded_file = root_folder.upload_file('/local/path/document.pdf')
print(f"Uploaded: {uploaded_file.name}")

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

# Upload with progress tracking for large files
large_file = root_folder.upload_file(
    '/local/path/large_video.mp4',
    chunk_size=5*1024*1024  # 5MB chunks
)

# Create a project folder structure
projects_folder = root_folder.create_folder('Projects')
current_project = projects_folder.create_folder('Current Project')

# Create subfolders
docs_folder = current_project.create_folder('Documents')
images_folder = current_project.create_folder('Images')
archived_folder = current_project.create_folder('Archived')

# Move files to appropriate folders
for item in root_folder.get_items():
    if item.is_file and item.name.endswith('.pdf'):
        item.move_to(docs_folder)
    elif item.is_file and item.name.endswith(('.jpg', '.png', '.gif')):
        item.move_to(images_folder)

# Create a public sharing link
document = drive.get_item(item_path='/Documents/report.pdf')
sharing_link = document.create_sharing_link(
    link_type='view',
    scope='anonymous'
)
print(f"Share URL: {sharing_link['web_url']}")

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

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

secure_link = document.create_sharing_link(
    link_type='edit',
    scope='organization',
    password='SecurePass123',
    expiration_date=datetime.now() + timedelta(days=7)
)

# Search for specific files
pdf_files = drive.search('type:pdf')
recent_files = drive.search('modified:>=2023-01-01')

# Filter by file properties
large_files = root_folder.get_items(
    size__gte=10*1024*1024,  # Files larger than 10MB
    limit=20
)

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

recent = datetime.now() - timedelta(days=7)
recent_files = root_folder.get_items(
    modified_time__gte=recent
)

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