mgtx-xlwings-utils 0.2.1

Reusable xlwings and pandas helpers for Excel automation workflows.

mgtx-xlwings-utils

Package-first xlwings and pandas helpers for Excel automation workflows at MeiraGTx.

---

What's new

0.2.1 — The post-save prompt is now a public function, offer_file_actions, with a new Copy file path button and an actions= argument to choose which of Open file / Open folder / Copy file path appear (save_dataframe(..., actions=...) forwards the same choice). Copying the path leaves the dialog open so you can still open the file or its folder; those close it. The copy now writes through the OS clipboard so it persists after the window closes.

0.2.0 — A formatting + dropdowns release. apply_table_features / apply_benchling_table_features apply column colours, prefill rows, and in-cell dropdowns in one call (Benchling enum columns become dropdowns automatically); paste_df_to_named_range is now format-preserving (borders="mesh"); paste_plate_data refreshes a plate without redrawing. Includes breaking renames/removals — see the changelog.

Full history: CHANGELOG.md.

---

Install

pip install mgtx-xlwings-utils

# With Benchling integration:
pip install "mgtx-xlwings-utils[benchling]"

For local development (editable install with test + build tooling):

pip install -e ".[dev]"

Python requirement: >=3.10.11,<4.0

---

Documentation

🌐 Live docs site: https://mgtx-data-science.github.io/xlwings_package/  ·  source: docs/index.md  ·  also mirrored on the GitHub Wiki.

Every guide is full-lifecycle — initialise → paste data in → read it back out → update → format → save — with inline Excel-grid diagrams showing exactly what to highlight and what each step does to the sheet.

Scenario guides

• Normal named-range tables — build a table by hand in Excel and drive it from Python (no Benchling).
• One Benchling table — pull a single result schema onto a sheet and write results back.
• Many Benchling tables (multi-sheet) — lay out several schemas across multiple sheets from a dict of ids.
• Plates — 6 / 12 / 24 / 48 / 96 / 384 / 1536-well and custom layouts with named-range round-trips.

Understand the engine

• Stacked tables & Benchling reinitialise — how managed tables stack (disjoint rows, danger zone, auto-heal), and how reinitialising with more columns auto-widens a table while protecting the neighbour below.

Reference & operational

• Full tools reference — every public function + exception, with verbatim signatures and examples.
• Credentials — constructing the Benchling ctx.
• Common patterns — config cells, dropdowns, sheet management, plotting, file IO.

---

Quickstart

import xlwings as xw
from xlwings_package import initialize_workbook, initialise_table_benchling

wb = xw.Book.caller()
initialize_workbook(wb)

# Pull a Benchling schema and lay it out on a sheet.
results = initialise_table_benchling(
    wb,
    {"Assay Results": ["assaysch_abc123"]},
    ctx=my_benchling_context,    # see the Credentials guide
)

See the single-Benchling guide for the full seven-step pattern (init → headers → read → transform → write → colour → save).

---

Testing

# Unit tests (no Excel required) — pure-Python fake workbook harness.
pytest tests/unit/ -q

# Integration tests (require a live Excel installation on Windows).
pytest tests/integration/ -q

Integration tests write inspectable artifacts to tests/integration/excel_table_tests/ — open any .xlsx to see what each test produced.

---

Debugging

Best-effort operations (cell merges, sheet moves, bookmark auto-heal) swallow Excel COM errors so they don't interrupt your workflow. To surface those errors during debugging:

import logging
logging.basicConfig(level=logging.DEBUG)

Production code paths that detect data-corruption risks (occupancy conflicts, column overflow, missing schema metadata) always raise — debug logs are only relevant for cosmetic / non-load-bearing failures.