Metadata-Version: 2.4
Name: mgtx-xlwings-utils
Version: 0.1.0
Summary: Reusable xlwings and pandas helpers for Excel automation workflows.
Author-email: Omar Eweis <omar.eweis@meiragtx.com>
Maintainer-email: Omar Eweis <omar.eweis@meiragtx.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MGTX-Data-Science/xlwings_package
Project-URL: Repository, https://github.com/MGTX-Data-Science/xlwings_package
Project-URL: Issues, https://github.com/MGTX-Data-Science/xlwings_package/issues
Keywords: xlwings,excel,pandas,automation,spreadsheet,benchling,office,com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xlwings>=0.30
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: webcolors>=1.13
Provides-Extra: benchling
Requires-Dist: mgtx-benchling-wrapper>=0.1.7; extra == "benchling"
Requires-Dist: keyring>=24.0; extra == "benchling"
Requires-Dist: cryptography>=41.0; extra == "benchling"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: pytest-profiling>=1.7; extra == "dev"
Requires-Dist: openpyxl>=3.1; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# mgtx-xlwings-utils

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

---

## Install

```bash
pip install mgtx-xlwings-utils

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

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

```bash
pip install -e ".[dev]"
```

Python requirement: `>=3.10.11,<4.0`

---

## Documentation

🌐 **Live docs site: <https://mgtx-data-science.github.io/xlwings_package/>**
&nbsp;·&nbsp; source: **[docs/index.md](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/index.md)**
&nbsp;·&nbsp; also mirrored on the **[GitHub Wiki](https://github.com/MGTX-Data-Science/xlwings_package/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](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/guides/normal-tables.md)**
  — build a table by hand in Excel and drive it from Python (no Benchling).
- **[One Benchling table](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/guides/benchling-single.md)**
  — pull a single result schema onto a sheet and write results back.
- **[Many Benchling tables (multi-sheet)](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/guides/benchling-multiple.md)**
  — lay out several schemas across multiple sheets from a dict of ids.
- **[Plates](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/guides/plates.md)**
  — 6 / 12 / 24 / 48 / 96 / 384 / 1536-well and custom layouts with
  named-range round-trips.

**Understand the engine**

- **[Stacked tables & Benchling reinitialise](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/concepts/stacked-tables-and-reinit.md)**
  — 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](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/reference/tools.md)**
  — every public function + exception, with verbatim signatures and examples.
- **[Credentials](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/credentials.md)**
  — constructing the Benchling `ctx`.
- **[Common patterns](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/common-patterns.md)**
  — config cells, dropdowns, sheet management, plotting, file IO.

---

## Quickstart

```python
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](https://github.com/MGTX-Data-Science/xlwings_package/blob/master/docs/guides/benchling-single.md)**
for the full seven-step pattern (init → headers → read → transform → write →
colour → save).

---

## Testing

```bash
# 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:

```python
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.
