CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-o365

O365 - Microsoft Graph and Office 365 API made easy

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

excel.mddocs/

Excel Integration

Microsoft Excel workbook and worksheet operations including cell manipulation, formula evaluation, and data analysis with session management for complex operations.

Capabilities

Excel Service Access

Access Excel workbooks stored in OneDrive for Business and SharePoint document libraries through the Microsoft Graph API.

def excel(self, resource: str = None) -> Excel:
    """
    Get an Excel service instance.
    
    Parameters:
    - resource: user resource identifier (defaults to authenticated user)
    
    Returns:
    - Excel: Excel service instance for workbook operations
    """

class Excel:
    def get_workbooks(self) -> list[Workbook]: ...
    def get_workbook(self, workbook_id: str) -> Workbook: ...

Workbook Management

Open and manage Excel workbooks with session support for efficient API operations and automatic session lifecycle management.

class WorkBook:
    def __init__(self, file_item, use_session: bool = True, persist: bool = True):
        """
        Create a workbook instance.
        
        Parameters:
        - file_item: Drive file item containing the Excel workbook
        - use_session: whether to use session for API operations
        - persist: whether to persist session changes
        """
    
    # Worksheet operations
    def get_worksheets(self) -> list[WorkSheet]: ...
    def get_worksheet(self, id_or_name: str) -> WorkSheet: ...
    def add_worksheet(self, name: str = None) -> WorkSheet: ...
    def delete_worksheet(self, worksheet_id: str) -> bool: ...
    
    # Table operations
    def get_tables(self) -> list[Table]: ...
    def get_table(self, id_or_name: str) -> Table: ...
    
    # Named range operations
    def get_named_ranges(self) -> list[NamedRange]: ...
    def get_named_range(self, name: str) -> NamedRange: ...
    def add_named_range(self, name: str, reference: str, comment: str = "", is_formula: bool = False) -> NamedRange: ...
    
    # Function execution
    def invoke_function(self, function_name: str, **function_params): ...
    
    # Application interface
    def get_workbookapplication(self) -> WorkbookApplication: ...

Worksheet Operations

Manage individual worksheets including cell ranges, tables, and named ranges with complete CRUD operations.

class WorkSheet:
    def __init__(self, parent: WorkBook = None, session: WorkbookSession = None, **kwargs): ...
    
    # Worksheet properties
    name: str  # Worksheet display name
    position: int  # Zero-based position in workbook
    visibility: str  # "Visible", "Hidden", "VeryHidden"
    
    # Worksheet management
    def delete(self) -> bool: ...
    def update(self, name: str = None, position: int = None, visibility: str = None) -> bool: ...
    
    # Range operations
    def get_range(self, address: str = None) -> Range: ...
    def get_used_range(self, only_values: bool = True) -> Range: ...
    def get_cell(self, row: int, column: int) -> Range: ...
    
    # Table operations
    def get_tables(self) -> list[Table]: ...
    def get_table(self, id_or_name: str) -> Table: ...
    def add_table(self, address: str, has_headers: bool) -> Table: ...
    
    # Named range operations
    def add_named_range(self, name: str, reference: str, comment: str = "", is_formula: bool = False) -> NamedRange: ...
    def get_named_range(self, name: str) -> NamedRange: ...

Range and Cell Operations

Comprehensive cell range manipulation including data access, formatting, formulas, and range navigation with support for bulk operations.

class Range:
    def __init__(self, parent=None, session=None, **kwargs): ...
    
    # Range properties (read-only)
    address: str  # Range address in A1-style notation
    address_local: str  # Range address in user's locale
    column_count: int  # Number of columns in range
    row_count: int  # Number of rows in range
    cell_count: int  # Total number of cells
    column_index: int  # Zero-based column index of first cell
    row_index: int  # Zero-based row index of first cell
    text: list[list]  # Text values in range
    value_types: list[list]  # Data types of each cell
    
    # Range data (with getters/setters)
    values: list[list]  # Raw cell values
    formulas: list[list]  # Formulas in A1-style notation
    formulas_local: list[list]  # Formulas in user's locale
    formulas_r1_c1: list[list]  # Formulas in R1C1-style notation
    number_format: list[list]  # Number format codes
    
    # Range navigation
    def get_cell(self, row: int, column: int) -> Range: ...
    def get_column(self, index: int) -> Range: ...
    def get_row(self, index: int) -> Range: ...
    def get_bounding_rect(self, address: str) -> Range: ...
    def get_columns_after(self, columns: int = 1) -> Range: ...
    def get_columns_before(self, columns: int = 1) -> Range: ...
    def get_entire_column(self) -> Range: ...
    def get_intersection(self, address: str) -> Range: ...
    def get_last_cell(self) -> Range: ...
    def get_last_column(self) -> Range: ...
    def get_last_row(self) -> Range: ...
    def get_offset_range(self, row_offset: int, column_offset: int) -> Range: ...
    def get_rows_above(self, rows: int = 1) -> Range: ...
    def get_rows_below(self, rows: int = 1) -> Range: ...
    def get_used_range(self, only_values: bool = True) -> Range: ...
    def get_resized_range(self, rows: int, columns: int) -> Range: ...
    
    # Range manipulation
    def clear(self, apply_to: str = "all") -> bool: ...  # "all", "formats", "contents"
    def delete(self, shift: str = "up") -> bool: ...  # "up", "left"
    def insert_range(self, shift: str) -> Range: ...  # "down", "right"
    def merge(self, across: bool = False) -> bool: ...
    def unmerge(self) -> bool: ...
    def update(self) -> bool: ...
    
    # Formatting
    def get_format(self) -> RangeFormat: ...

Range Formatting

Complete cell and range formatting including fonts, colors, alignment, borders, and number formats with comprehensive styling options.

class RangeFormat:
    def __init__(self, parent=None, session=None, **kwargs): ...
    
    # Format properties (with getters/setters)
    column_width: float  # Width of columns in range
    row_height: float  # Height of rows in range
    horizontal_alignment: str  # "General", "Left", "Center", "Right", "Fill", "Justify", "CenterAcrossSelection", "Distributed"
    vertical_alignment: str  # "Top", "Center", "Bottom", "Justify", "Distributed"
    wrap_text: bool  # Text wrapping setting
    background_color: str  # Background fill color
    font: RangeFormatFont  # Font formatting object
    
    # Format operations
    def update(self) -> bool: ...
    def auto_fit_columns(self) -> bool: ...
    def auto_fit_rows(self) -> bool: ...
    def set_borders(self, side_style: str = ""): ...

class RangeFormatFont:
    def __init__(self, parent): ...
    
    # Font properties (with getters/setters)
    bold: bool  # Font boldness
    color: str  # Font color (hex format, default: "#000000")
    italic: bool  # Font italic style
    name: str  # Font name (default: "Calibri")
    size: int  # Font size (default: 10)
    underline: str  # Underline style (default: "None")

Table Management

Excel table operations including structured data management, column operations, row manipulation, and filtering with automatic formatting.

class Table:
    def __init__(self, parent=None, session=None, **kwargs): ...
    
    # Table properties
    object_id: str  # Unique table identifier
    name: str  # Table name
    show_headers: bool  # Header row visibility
    show_totals: bool  # Total row visibility
    style: str  # Table style name
    highlight_first_column: bool  # First column highlighting
    highlight_last_column: bool  # Last column highlighting
    show_banded_columns: bool  # Column banding
    show_banded_rows: bool  # Row banding
    show_filter_button: bool  # Filter button visibility
    
    # Column management
    def get_columns(self, top: int = None, skip: int = None) -> Iterator[TableColumn]: ...
    def get_column(self, id_or_name: str) -> TableColumn: ...
    def get_column_at_index(self, index: int) -> TableColumn: ...
    def delete_column(self, id_or_name: str) -> bool: ...
    def add_column(self, name: str, index: int = 0, values: list = None) -> TableColumn: ...
    
    # Row management
    def get_rows(self, top: int = None, skip: int = None) -> Iterator[TableRow]: ...
    def get_row(self, index: int) -> TableRow: ...
    def get_row_at_index(self, index: int) -> TableRow: ...
    def delete_row(self, index: int) -> bool: ...
    def add_rows(self, values: list = None, index: int = None) -> TableRow: ...
    
    # Range methods
    def get_data_body_range(self) -> Range: ...
    def get_header_row_range(self) -> Range: ...
    def get_total_row_range(self) -> Range: ...
    def get_range(self) -> Range: ...
    def convert_to_range(self) -> Range: ...
    
    # Filter methods
    def clear_filters(self) -> bool: ...
    def reapply_filters(self) -> bool: ...
    
    # Table operations
    def update(self, name: str = None, show_headers: bool = None, show_totals: bool = None, style: str = None) -> bool: ...
    def delete(self) -> bool: ...

class TableColumn:
    def __init__(self, parent=None, session=None, **kwargs): ...
    
    # Column properties
    object_id: str  # Column identifier
    name: str  # Column name
    index: int  # Zero-based column index
    values: list[list]  # Column values
    
    # Column operations
    def delete(self) -> bool: ...
    def update(self, values: list) -> bool: ...
    def get_data_body_range(self) -> Range: ...
    def get_header_row_range(self) -> Range: ...
    def get_total_row_range(self) -> Range: ...
    def get_range(self) -> Range: ...
    def clear_filter(self) -> bool: ...
    def apply_filter(self, criteria): ...

class TableRow:
    def __init__(self, parent=None, session=None, **kwargs): ...
    
    # Row properties
    object_id: str  # Row identifier (index)
    index: int  # Zero-based row index
    values: list[list]  # Row values
    
    # Row operations
    def get_range(self) -> Range: ...
    def update(self, values: list) -> bool: ...
    def delete(self) -> bool: ...

Named Ranges

Named range management for creating reusable cell references and formulas with support for workbook and worksheet scopes.

class NamedRange:
    def __init__(self, parent=None, session=None, **kwargs): ...
    
    # Named range properties (read-only)
    object_id: str  # Named range identifier
    name: str  # Name of the range
    comment: str  # Associated comment
    scope: str  # Scope (workbook or worksheet)
    data_type: str  # "String", "Integer", "Double", "Boolean", "Range"
    value: str  # Formula or value definition
    visible: bool  # Visibility status
    
    # Named range operations
    def get_range(self) -> Range: ...
    def update(self, visible: bool = None, comment: str = None) -> bool: ...

Session Management

Workbook session management for efficient API operations with automatic session lifecycle, timeout handling, and persistence control.

class WorkbookSession:
    def __init__(self, parent=None, con=None, persist: bool = True, **kwargs): ...
    
    # Session properties
    persist: bool  # Whether session changes are persisted
    session_id: str  # The session identifier
    last_activity: datetime  # Time of last activity
    inactivity_limit: timedelta  # Session timeout limit
    
    # Session operations
    def create_session(self) -> bool: ...
    def refresh_session(self) -> bool: ...
    def close_session(self) -> bool: ...
    def prepare_request(self, kwargs): ...

Application Interface

Workbook application operations including calculation management and application-level settings.

class WorkbookApplication:
    def __init__(self, workbook: WorkBook): ...
    
    # Application operations
    def get_details(self) -> dict: ...
    def run_calculations(self, calculation_type: str) -> bool: ...  # "Recalculate", "Full", "FullRebuild"

Types

# Session timeout constants
PERSISTENT_SESSION_INACTIVITY_MAX_AGE = 420  # 7 minutes in seconds
NON_PERSISTENT_SESSION_INACTIVITY_MAX_AGE = 300  # 5 minutes in seconds

# Excel MIME type
EXCEL_XLSX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

# Exception types
class FunctionException(Exception):
    """Exception raised when Excel function invocation fails."""

# Alignment options
HorizontalAlignment = Literal["General", "Left", "Center", "Right", "Fill", "Justify", "CenterAcrossSelection", "Distributed"]
VerticalAlignment = Literal["Top", "Center", "Bottom", "Justify", "Distributed"]

# Worksheet visibility options
WorksheetVisibility = Literal["Visible", "Hidden", "VeryHidden"]

# Range clear options
RangeClearType = Literal["all", "formats", "contents"]

# Range shift options
RangeShiftDirection = Literal["up", "left", "down", "right"]

# Calculation types
CalculationType = Literal["Recalculate", "Full", "FullRebuild"]

Usage Examples

Basic Workbook Operations

from O365 import Account

# Set up account and get file
account = Account(credentials)
storage = account.storage()
drive = storage.get_default_drive()
excel_file = drive.get_item_by_path("/path/to/workbook.xlsx")

# Create workbook with session
workbook = WorkBook(excel_file, use_session=True, persist=True)

# Access worksheets
worksheets = workbook.get_worksheets()
worksheet = workbook.get_worksheet("Sheet1")

# Work with ranges
range_obj = worksheet.get_range("A1:B10")
range_obj.values = [[1, 2], [3, 4], [5, 6]]
range_obj.update()

# Format ranges
format_obj = range_obj.get_format()
format_obj.font.bold = True
format_obj.font.color = "#FF0000"
format_obj.background_color = "#FFFF00"
format_obj.horizontal_alignment = "Center"
format_obj.update()

Table Operations

# Create and work with tables
table = worksheet.add_table("A1:D10", has_headers=True)

# Add data to table
table.add_rows([
    ["John", "Doe", 30, "Engineer"],
    ["Jane", "Smith", 25, "Designer"]
])

# Add new column
salary_column = table.add_column("Salary", values=[[50000], [45000]])

# Access table data
columns = table.get_columns()
rows = table.get_rows()

# Apply filters
for column in columns:
    if column.name == "Age":
        column.apply_filter({"filterOn": "values", "values": ["30"]})

Named Ranges and Formulas

# Create named ranges
workbook.add_named_range("SalesData", "Sheet1!A1:D10", "Sales figures for Q1")
workbook.add_named_range("TaxRate", "0.08", "Current tax rate", is_formula=True)

# Use named ranges in formulas
summary_range = worksheet.get_range("F1:F5")
summary_range.formulas = [
    ["=SUM(SalesData)"],
    ["=AVERAGE(SalesData)"],
    ["=MAX(SalesData)"],
    ["=MIN(SalesData)"],
    ["=SUM(SalesData)*TaxRate"]
]
summary_range.update()

# Execute Excel functions
result = workbook.invoke_function("VLOOKUP", 
                                  lookup_value="John",
                                  table_array="A1:D10", 
                                  col_index_num=3,
                                  range_lookup=False)

Install with Tessl CLI

npx tessl i tessl/pypi-o365

docs

authentication.md

calendar.md

contacts.md

directory.md

email.md

excel.md

index.md

sharepoint.md

storage.md

tasks.md

teams.md

tile.json