gridient package

Submodules

gridient.layout module

class gridient.layout.ExcelLayout(workbook: ExcelWorkbook)

Bases: object

Top-level layout manager for the workbook. Orchestrates writing.

add_sheet(sheet: ExcelSheetLayout) → None

Add a sheet layout to the workbook.

write() → None

Assign references, write all components to Excel, and close workbook.

class gridient.layout.ExcelSheetLayout(name: str, auto_width: bool = True)

Bases: object

Manages component layout for a single worksheet.

add(component: Any, row: int, col: int, direction: str | None = 'down') → None

Add a component at a specific position with optional direction.

get_components() → List[PlacedComponent]

class gridient.layout.PlacedComponent(component: Any, row: int, col: int, direction: str | None = 'down')

Bases: object

col: int

component: Any

direction: str | None = 'down'

row: int

gridient.stacks module

class gridient.stacks.ExcelStack(orientation: str, children: ~typing.List[~typing.Any] = <factory>, padding: int = 0, spacing: int = 1, name: str | None = None)

Bases: object

A container for arranging layout components vertically or horizontally.

add(component: Any)

Add a component (ExcelValue, ExcelTable, ExcelSeries, ExcelStack) to the stack.

children: List[Any]

get_size() → Tuple[int, int]

Calculate and return the total size (rows, columns) of the stack including padding.

name: str | None = None

orientation: str

padding: int = 0

spacing: int = 1

write(worksheet: xlsxwriter.worksheet.Worksheet, start_row: int, start_col: int, workbook_wrapper: ExcelWorkbook, ref_map: dict, column_widths: dict)

Write the stack’s children to the worksheet.

gridient.styling module

class gridient.styling.ExcelStyle(bold: bool = False, italic: bool = False, font_color: str | None = None, bg_color: str | None = None)

Bases: object

Defines visual styling for Excel elements.

bg_color: str | None = None

bold: bool = False

font_color: str | None = None

get_xlsxwriter_format(workbook)

Get or create the xlsxwriter format object for this style.

italic: bool = False

gridient.tables module

class gridient.tables.ExcelParameterTable(title: str | None = None, parameters: List[ExcelValue] | None = None)

Bases: object

Specialized table for displaying named parameters (Name, Value, Unit).

add(value: ExcelValue) → None

Add a parameter to the table.

get_size() → Tuple[int, int]

Calculate the size (rows, columns) of the parameter table.

write(worksheet: Any, row: int, col: int, workbook_wrapper: ExcelWorkbook, ref_map: dict, column_widths: Dict[int, float] | None = None)

Writes the parameter table to Excel.

class gridient.tables.ExcelTable(title: str | None = None, columns: List[ExcelTableColumn | ExcelSeries] | None = None)

Bases: object

Represents a table of values with columns and an optional title.

add_column(column: ExcelTableColumn | ExcelSeries) → None

Add a column to the table.

get_size() → Tuple[int, int]

Calculate the size (rows, columns) of the table.

write(worksheet: Any, row: int, col: int, workbook_wrapper: ExcelWorkbook, ref_map: dict, column_widths: Dict[int, float] | None = None)

Writes the table to Excel.

class gridient.tables.ExcelTableColumn(series: ExcelSeries)

Bases: object

Represents a single column within an ExcelTable.

series: ExcelSeries

gridient.values module

class gridient.values.ExcelFormula(operator_or_function: str, arguments: ~typing.List[~typing.Any] = <factory>)

Bases: object

Represents an Excel formula or function call.

arguments: List[Any]

get_precedence() → int

Returns the precedence of the current operator.

operator_or_function: str

operator_precedence = {'*': 3, '+': 2, '-': 2, '/': 3, '<': 1, '<=': 1, '<>': 1, '=': 1, '>': 1, '>=': 1, '^': 4}

render(current_sheet_name: str, ref_map: Dict[int, Tuple[str, str]]) → str

Renders the formula to its Excel string representation with proper parentheses.

class gridient.values.ExcelSeries(name: str | None = None, format: str | None = None, style: ExcelStyle | None = None, index: list | None = None, data: dict | list | None = None)

Bases: object

Represents a series of Excel values, potentially indexed.

classmethod from_pandas(series: Series, name: str | None = None, format: str | None = None, style: ExcelStyle | None = None)

Create an ExcelSeries from a pandas Series.

class gridient.values.ExcelValue(value: Any, name: str | None = None, format: str | None = None, unit: str | None = None, style: ExcelStyle | None = None, _id: int | None = None, is_parameter: bool = False)

Bases: object

Base class for any value that can be written to Excel.

property excel_ref: str

Returns the Excel cell reference (e.g., ‘A1’) for this value once placed.

get_size() → Tuple[int, int]

Return the size of a single value: (1 row, 1 column).

property value

write(worksheet: Worksheet, row: int, col: int, workbook_wrapper, ref_map: Dict[int, Tuple[str, str]], column_widths: Dict[int, float] | None = None)

Writes the value to Excel at the specified position and updates column width.

gridient.workbook module

class gridient.workbook.ExcelWorkbook(filename: str)

Bases: object

Wrapper for xlsxwriter.Workbook with format caching.

add_worksheet(name: str | None = None)

Add a new worksheet to the workbook with name validation.

close()

Close the workbook file.

get_combined_format(style: ExcelStyle | None, num_format: str | None)

Get or create a cached xlsxwriter format object combining style and number format.

validate_worksheet_name(name: str | None) → None

Validate worksheet name according to Excel rules.

Rules: - Names cannot be blank - Names cannot contain more than 31 characters - Names cannot contain any of these characters: / ? * : [ ] - Names cannot begin or end with an apostrophe (‘) - Names cannot be the reserved word “History”

Raises ValueError if the name is invalid.

Module contents

ExcelAlchemy: Write Python calculations to Excel with live formulas.

class gridient.ExcelFormula(operator_or_function: str, arguments: ~typing.List[~typing.Any] = <factory>)

Bases: object

Represents an Excel formula or function call.

arguments: List[Any]

get_precedence() → int

Returns the precedence of the current operator.

operator_or_function: str

operator_precedence = {'*': 3, '+': 2, '-': 2, '/': 3, '<': 1, '<=': 1, '<>': 1, '=': 1, '>': 1, '>=': 1, '^': 4}

render(current_sheet_name: str, ref_map: Dict[int, Tuple[str, str]]) → str

Renders the formula to its Excel string representation with proper parentheses.

class gridient.ExcelLayout(workbook: ExcelWorkbook)

Bases: object

Top-level layout manager for the workbook. Orchestrates writing.

add_sheet(sheet: ExcelSheetLayout) → None

Add a sheet layout to the workbook.

write() → None

Assign references, write all components to Excel, and close workbook.

class gridient.ExcelParameterTable(title: str | None = None, parameters: List[ExcelValue] | None = None)

Bases: object

Specialized table for displaying named parameters (Name, Value, Unit).

add(value: ExcelValue) → None

Add a parameter to the table.

get_size() → Tuple[int, int]

Calculate the size (rows, columns) of the parameter table.

write(worksheet: Any, row: int, col: int, workbook_wrapper: ExcelWorkbook, ref_map: dict, column_widths: Dict[int, float] | None = None)

Writes the parameter table to Excel.

class gridient.ExcelSeries(name: str | None = None, format: str | None = None, style: ExcelStyle | None = None, index: list | None = None, data: dict | list | None = None)

Bases: object

Represents a series of Excel values, potentially indexed.

classmethod from_pandas(series: Series, name: str | None = None, format: str | None = None, style: ExcelStyle | None = None)

Create an ExcelSeries from a pandas Series.

class gridient.ExcelSheetLayout(name: str, auto_width: bool = True)

Bases: object

Manages component layout for a single worksheet.

add(component: Any, row: int, col: int, direction: str | None = 'down') → None

Add a component at a specific position with optional direction.

get_components() → List[PlacedComponent]

class gridient.ExcelStack(orientation: str, children: ~typing.List[~typing.Any] = <factory>, padding: int = 0, spacing: int = 1, name: str | None = None)

Bases: object

A container for arranging layout components vertically or horizontally.

add(component: Any)

Add a component (ExcelValue, ExcelTable, ExcelSeries, ExcelStack) to the stack.

children: List[Any]

get_size() → Tuple[int, int]

Calculate and return the total size (rows, columns) of the stack including padding.

name: str | None = None

orientation: str

padding: int = 0

spacing: int = 1

write(worksheet: xlsxwriter.worksheet.Worksheet, start_row: int, start_col: int, workbook_wrapper: ExcelWorkbook, ref_map: dict, column_widths: dict)

Write the stack’s children to the worksheet.

class gridient.ExcelStyle(bold: bool = False, italic: bool = False, font_color: str | None = None, bg_color: str | None = None)

Bases: object

Defines visual styling for Excel elements.

bg_color: str | None = None

bold: bool = False

font_color: str | None = None

get_xlsxwriter_format(workbook)

Get or create the xlsxwriter format object for this style.

italic: bool = False

class gridient.ExcelTable(title: str | None = None, columns: List[ExcelTableColumn | ExcelSeries] | None = None)

Bases: object

Represents a table of values with columns and an optional title.

add_column(column: ExcelTableColumn | ExcelSeries) → None

Add a column to the table.

get_size() → Tuple[int, int]

Calculate the size (rows, columns) of the table.

write(worksheet: Any, row: int, col: int, workbook_wrapper: ExcelWorkbook, ref_map: dict, column_widths: Dict[int, float] | None = None)

Writes the table to Excel.

class gridient.ExcelTableColumn(series: ExcelSeries)

Bases: object

Represents a single column within an ExcelTable.

series: ExcelSeries

class gridient.ExcelValue(value: Any, name: str | None = None, format: str | None = None, unit: str | None = None, style: ExcelStyle | None = None, _id: int | None = None, is_parameter: bool = False)

Bases: object

Base class for any value that can be written to Excel.

property excel_ref: str

Returns the Excel cell reference (e.g., ‘A1’) for this value once placed.

get_size() → Tuple[int, int]

Return the size of a single value: (1 row, 1 column).

property value

write(worksheet: Worksheet, row: int, col: int, workbook_wrapper, ref_map: Dict[int, Tuple[str, str]], column_widths: Dict[int, float] | None = None)

Writes the value to Excel at the specified position and updates column width.

class gridient.ExcelWorkbook(filename: str)

Bases: object

Wrapper for xlsxwriter.Workbook with format caching.

add_worksheet(name: str | None = None)

Add a new worksheet to the workbook with name validation.

close()

Close the workbook file.

get_combined_format(style: ExcelStyle | None, num_format: str | None)

Get or create a cached xlsxwriter format object combining style and number format.

validate_worksheet_name(name: str | None) → None

Validate worksheet name according to Excel rules.

Rules: - Names cannot be blank - Names cannot contain more than 31 characters - Names cannot contain any of these characters: / ? * : [ ] - Names cannot begin or end with an apostrophe (‘) - Names cannot be the reserved word “History”

Raises ValueError if the name is invalid.