mgtx-xlwings-utils 0.2.0

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.1.35 — Autopaste (initialise_table_benchling(mode="autopaste")) now leaves table_gap blank rows below a manually built table or notes, not just below other managed tables. Previously a Benchling table placed under a hand-made table had no separation and its title row stuck to the content above. Pass table_gap=0 to restore the old flush placement.

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.