Spreadsheet Management

class Client:
    def create(self, title, template=None, folder=None, folder_name=None, **kwargs) -> Spreadsheet:
        """
        Create a new spreadsheet.
        
        Parameters:
        - title (str): Name of the new spreadsheet
        - template (Spreadsheet): Spreadsheet to use as template
        - folder (str): Folder ID where spreadsheet should be created
        - folder_name (str): Name of folder where spreadsheet should be created
        
        Returns:
        Spreadsheet: New spreadsheet instance
        """

class Client:
    def open(self, title) -> Spreadsheet:
        """
        Open spreadsheet by title.
        
        Parameters:
        - title (str): Title of the spreadsheet
        
        Returns:
        Spreadsheet: Opened spreadsheet instance
        
        Raises:
        SpreadsheetNotFound: If no spreadsheet with given title is found
        """
    
    def open_by_key(self, key) -> Spreadsheet:
        """
        Open spreadsheet by key/ID.
        
        Parameters:
        - key (str): Spreadsheet key/ID
        
        Returns:
        Spreadsheet: Opened spreadsheet instance
        """
    
    def open_by_url(self, url) -> Spreadsheet:
        """
        Open spreadsheet by URL.
        
        Parameters:
        - url (str): Full URL of the spreadsheet
        
        Returns:
        Spreadsheet: Opened spreadsheet instance
        
        Raises:
        NoValidUrlKeyFound: If URL doesn't contain valid spreadsheet key
        """
    
    def open_all(self, query='') -> list:
        """
        Open all accessible spreadsheets matching query.
        
        Parameters:
        - query (str): Search query to filter spreadsheets
        
        Returns:
        list: List of Spreadsheet instances
        """

class Spreadsheet:
    def __init__(self, client, jsonsheet=None, id=None):
        """
        Initialize spreadsheet instance.
        
        Parameters:
        - client (Client): Authenticated client instance
        - properties (dict): Spreadsheet properties
        - jsonsheet (dict): Full spreadsheet JSON representation
        """
    
    @property
    def id(self) -> str:
        """Spreadsheet ID."""
    
    @property
    def title(self) -> str:
        """Spreadsheet title."""
    
    @property
    def url(self) -> str:
        """Spreadsheet URL."""
    
    @property
    def locale(self) -> str:
        """Spreadsheet locale."""
    
    @property
    def sheet1(self) -> Worksheet:
        """First worksheet in the spreadsheet."""
    
    def fetch_properties(self, jsonsheet=None):
        """
        Fetch and update spreadsheet properties from API.
        
        Parameters:
        - jsonsheet (dict): Optional JSON representation to use instead of API call
        """
    
    def worksheets(self, sheet_property=None, value=None, force_fetch=False) -> list:
        """
        Get list of all worksheets in spreadsheet.
        
        Parameters:
        - property (WorkSheetProperty): Property to return for each worksheet
        
        Returns:
        list: List of worksheet titles, IDs, or indices based on property parameter
        """
    
    def worksheet(self, property=WorkSheetProperty.TITLE, value=0) -> Worksheet:
        """
        Get specific worksheet by property value.
        
        Parameters:
        - property (WorkSheetProperty): Property to search by
        - value: Value to match
        
        Returns:
        Worksheet: Matching worksheet instance
        
        Raises:
        WorksheetNotFound: If no matching worksheet is found
        """
    
    def add_worksheet(self, title, rows=100, cols=26, src_tuple=None, src_worksheet=None, index=None) -> Worksheet:
        """
        Create or copy a worksheet and add it to the spreadsheet.
        
        Parameters:
        - title (str): Title of the new worksheet
        - rows (int): Number of rows (default: 100)
        - cols (int): Number of columns (default: 26)
        - src_tuple (tuple): Source spreadsheet tuple for copying
        - src_worksheet: Source worksheet to copy from
        - index (int): Position to insert the worksheet
        
        Returns:
        Worksheet: The newly created worksheet
        """
    
    def del_worksheet(self, worksheet):
        """
        Delete a worksheet from the spreadsheet.
        
        Parameters:
        - worksheet: The worksheet instance to delete
        """

class Spreadsheet:
    def share(self, addr, role='reader', typ='user', **kwargs):
        """
        Share spreadsheet with user or group.
        
        Parameters:
        - addr (str): Email address or domain to share with
        - role (str): Permission role ('owner', 'writer', 'reader')
        - typ (str): Type of recipient ('user', 'group', 'domain', 'anyone')
        - **kwargs: Additional sharing options
        """
    
    def remove_permission(self, addr):
        """
        Remove sharing permission for user or group.
        
        Parameters:
        - addr (str): Email address or domain to remove permission from
        
        Raises:
        CannotRemoveOwnerError: If trying to remove last owner permission
        """
    
    @property
    def permissions(self) -> list:
        """
        List of current sharing permissions.
        
        Returns:
        list: List of permission dictionaries
        """

class Spreadsheet:
    def export(self, file_format=ExportType.CSV, filename=None, path='') -> str:
        """
        Export spreadsheet to file.
        
        Parameters:
        - file_format (ExportType): Export format (CSV, XLS, PDF, etc.)
        - filename (str): Name for exported file
        - path (str): Directory path for export
        
        Returns:
        str: Path to exported file
        """
    
    def delete(self):
        """
        Delete the spreadsheet.
        
        Raises:
        RequestError: If deletion fails
        """
    
    def to_json(self) -> dict:
        """
        Get JSON representation of spreadsheet.
        
        Returns:
        dict: Complete spreadsheet data as JSON
        """

import pygsheets

# Authenticate
gc = pygsheets.authorize()

# Create new spreadsheet
sh = gc.create('My New Spreadsheet')

# Open existing spreadsheet by title
sh = gc.open('Existing Spreadsheet')

# Open by key/ID
sh = gc.open_by_key('1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms')

# Open by URL
url = 'https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'
sh = gc.open_by_url(url)

# Get all spreadsheets
all_sheets = gc.open_all()

# Search for specific spreadsheets
finance_sheets = gc.open_all('finance')

# Share with specific user
sh.share('user@example.com', role='writer')

# Share with domain
sh.share('example.com', role='reader', typ='domain')

# Make publicly readable
sh.share('', role='reader', typ='anyone')

# Remove permission
sh.remove_permission('user@example.com')

# Check current permissions
permissions = sh.permissions
for perm in permissions:
    print(f"Email: {perm.get('emailAddress')}, Role: {perm.get('role')}")

class ExportType:
    XLS = 'application/vnd.ms-excel'
    ODT = 'application/vnd.oasis.opendocument.text'
    PDF = 'application/pdf'
    CSV = 'text/csv'
    TSV = 'text/tab-separated-values'
    HTML = 'text/html'

class WorkSheetProperty:
    TITLE = 'title'
    ID = 'id'
    INDEX = 'index'

class SpreadsheetNotFound(PyGsheetsException):
    """Raised when spreadsheet cannot be found or accessed."""
    pass

class NoValidUrlKeyFound(PyGsheetsException):
    """Raised when URL doesn't contain valid spreadsheet key."""
    pass

class CannotRemoveOwnerError(PyGsheetsException):
    """Raised when trying to remove last owner permission."""
    pass