pyOpenVBA 5.2.0__tar.gz → 5.2.2__tar.gz

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyOpenVBA
-Version: 5.2.0
+Version: 5.2.2
 Summary: Read and write VBA macros and Excel Power Query in pure Python, no dependencies.
 Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyOpenVBA
 Project-URL: Repository, https://github.com/WilliamSmithEdward/pyOpenVBA
@@ -29,6 +29,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
 Requires-Dist: pyright>=1.1.350; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: twine>=5; extra == 'dev'
@@ -55,7 +56,7 @@ VBA, four hosts and one API:
 * PowerPoint (`.pptm`, `.potm`, `.ppt`)
 * Access (`.accdb`, `.mdb`)
 
-Power Query, in any Excel package (`.xlsx` included):
+Power Query, in any Excel package:
 
 ```python
 from pyopenvba import PowerQueryWorkbook

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/README.md

@@ -19,7 +19,7 @@ VBA, four hosts and one API:
 * PowerPoint (`.pptm`, `.potm`, `.ppt`)
 * Access (`.accdb`, `.mdb`)
 
-Power Query, in any Excel package (`.xlsx` included):
+Power Query, in any Excel package:
 
 ```python
 from pyopenvba import PowerQueryWorkbook

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/docs/power_query.md

@@ -221,6 +221,13 @@ wrong: **a connections part holding no connections is one Excel refuses**,
 so removing the last connection removes the part, its content type and
 its relationship as well.
 
+The hidden name has a rule of its own. **`localSheetId` is the zero-based
+position of the sheet the name belongs to** among the workbook's sheets,
+not a constant, and it has to agree with the sheet the reference names.
+Written as 0 it was right only while the table landed on the first sheet;
+anywhere else Excel refuses to open the workbook, which is invisible in a
+one-sheet file and so went unnoticed.
+
 ### Refresh control
 
 The boxes in Excel's Connection Properties dialog belong to that
@@ -277,6 +284,47 @@ this file exists because nothing here is written on a guess.
 
 ---
 
+## Workbooks another tool wrote
+
+Excel is not the only writer of `.xlsx`, and the parts it produces are
+one legal spelling among several. Three assumptions here came from
+reading only Excel's output, and each one broke on openpyxl's:
+
+* **Attribute order carries no meaning.** Excel opens a relationship with
+  `Id`, openpyxl closes with it. Matching in a fixed order found nothing,
+  so a sheet looked as though it had no part behind it and loading to it
+  failed outright.
+* **An empty element may be written closed.** `<definedNames />` is the
+  same element as `<definedNames></definedNames>`. Appending a second
+  block beside it left two in the workbook, which Excel refuses.
+* **A namespace prefix is declared where it is used.** Excel puts
+  `xmlns:r` on every worksheet; openpyxl puts it on a worksheet that
+  needs one, and a sheet with no table does not. Adding a `tablePart`
+  that used the prefix made the part not well formed.
+
+Loading a query onto a sheet of a workbook openpyxl wrote works, and
+Excel opens and refreshes the result.
+
+**The other direction does not, and cannot be fixed here.** openpyxl
+rebuilds the package from the parts it models and drops the rest, custom
+XML included, so saving a workbook through it removes the Power Query
+package and the queries with it. Nothing signals this: the file opens and
+simply has no queries. Put pyOpenVBA last in the pipeline, or carry the
+queries across with `pull_queries()` and `push_queries()`.
+
+## `[trash]` parts
+
+Excel's own file recovery leaves the parts it threw out under
+`[trash]/NNNN.dat`, beside the real ones. An OPC part name cannot open a
+segment with a bracket, and Excel holds itself to that when reading: the
+same workbook opens before such an entry is added and fails to open at
+all after, measured both ways.
+
+The container preserves every entry as it arrived, which would hand back
+a file that stays broken, so `save()` drops these and warns. Nothing in
+the document depends on them: they carry no content type and no
+relationship points at them.
+
 ## What Excel refuses
 
 * A query name containing a dot. `Queries.Add` rejects it with

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyOpenVBA"
-version = "5.2.0"
+version = "5.2.2"
 description = "Read and write VBA macros and Excel Power Query in pure Python, no dependencies."
 readme = "README.md"
 license = { text = "MIT" }
@@ -61,6 +61,10 @@ dev = [
     "pyright>=1.1.350",
     "build>=1.2",
     "twine>=5",
+    # Test-time only, and the runtime keeps its promise of no dependencies.
+    # openpyxl writes the same parts a different legal way, which is what
+    # the interop tests are for.
+    "openpyxl>=3.1",
 ]
 
 [project.urls]

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/src/pyopenvba/__init__.py

@@ -291,4 +291,4 @@ def push_power_query(
     """
     return _push_queries(src_dir, workbook, out=out, encoding=encoding, remove_missing=remove_missing)
 
-__version__ = "5.2.0"
+__version__ = "5.2.2"

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/src/pyopenvba/powerquery/_opc.py

@@ -29,6 +29,9 @@ _STORED = 0
 _FLAGS = 0x0006
 _MADE_BY = 45
 _NEEDED = 20
+#: Where Excel's file recovery parks the parts it threw out.  Not a legal
+#: OPC part name, and Excel will not open a package holding one.
+_RESERVED = "[trash]/"
 
 
 @dataclass
@@ -174,6 +177,28 @@ class OpcFile:
             self.entries = kept
             self.source = None
 
+    def drop_reserved(self) -> list[str]:
+        """Take out entries whose names are not part names, and say which.
+
+        Excel's own file recovery leaves `[trash]/NNNN.dat` beside the
+        real parts.  An OPC part name is built of segments that cannot
+        open with a bracket, and Excel holds itself to that when reading:
+        a workbook that opens cleanly stops opening at all once such an
+        entry is added, which is measured both ways in
+        `tests/test_powerquery_opc.py`.
+
+        Nothing in the document depends on them.  They carry no content
+        type and no relationship points at them, so a package is repaired
+        by dropping them rather than damaged.
+        """
+        doomed = [entry.name for entry in self.entries if entry.name.startswith(_RESERVED)]
+        if doomed:
+            self.entries = [
+                entry for entry in self.entries if not entry.name.startswith(_RESERVED)
+            ]
+            self.source = None
+        return doomed
+
     def serialize(self) -> bytes:
         if self.source is not None:
             return self.source

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/src/pyopenvba/powerquery/_sheets.py

@@ -102,6 +102,38 @@ def _relationships(package: OpcFile, part: str) -> str:
     )
 
 
+def _attributes(element: str) -> dict[str, str]:
+    """The attributes of one element, in whatever order they were written.
+
+    XML gives attribute order no meaning, and writers differ: Excel opens
+    a relationship with ``Id``, openpyxl closes with it.  Matching them in
+    a fixed order silently found nothing in the second case, which left a
+    sheet looking as though it had no part behind it.
+    """
+    return dict(re.findall(r'([\w.:-]+)\s*=\s*"([^"]*)"', element))
+
+
+def _relationship_targets(rels: str) -> dict[str, str]:
+    """``{relationship id: target}`` for one ``.rels`` part."""
+    out: dict[str, str] = {}
+    for element in re.findall(r"<Relationship\b[^>]*>", rels):
+        attributes = _attributes(element)
+        identifier, target = attributes.get("Id"), attributes.get("Target")
+        if identifier and target is not None:
+            out[identifier] = target
+    return out
+
+
+def _relationship_for(rels: str, target: str) -> str | None:
+    """The id pointing at ``target``, comparing the part it names rather
+    than the spelling: a target may be relative or absolute."""
+    wanted = target.lstrip("/").removeprefix("../")
+    for identifier, found in _relationship_targets(rels).items():
+        if found.lstrip("/").removeprefix("../") == wanted:
+            return identifier
+    return None
+
+
 def add_relationship(package: OpcFile, part: str, kind: str, target: str) -> str:
     raw = _relationships(package, part)
     identifier = _next_relationship(raw)
@@ -137,13 +169,44 @@ def drop_content_type(package: OpcFile, part: str) -> None:
     )
 
 
+def sheet_entries(workbook: str) -> list[tuple[str, str]]:
+    """``(name, relationship id)`` for each sheet, in the order the
+    workbook lists them.
+
+    The order is load-bearing: a ``definedName`` names the sheet it is
+    local to by its position here, so the list is the one place that
+    settles both which part a sheet is and what index it has.
+    """
+    out: list[tuple[str, str]] = []
+    for element in re.findall(r"<sheet\b[^>]*>", workbook):
+        attributes = _attributes(element)
+        # The relationship attribute carries a namespace prefix, and which
+        # prefix is the writer's to choose.
+        identifier = next(
+            (value for key, value in attributes.items() if key.endswith(":id")), None
+        )
+        if "name" in attributes and identifier:
+            out.append((attributes["name"], identifier))
+    return out
+
+
+def sheet_index(package: OpcFile, name: str) -> int:
+    """A sheet's zero-based position among the workbook's sheets."""
+    sheets = sheet_entries(package.read(_WORKBOOK).decode("utf-8"))
+    for index, (found, _identifier) in enumerate(sheets):
+        if found == name:
+            return index
+    known = ", ".join(pair[0] for pair in sheets)
+    raise PowerQueryError(f"this workbook has no sheet named {name!r}; it has: {known}")
+
+
 def sheet_part(package: OpcFile, sheet: str | int) -> tuple[str, str]:
     """The worksheet part for a sheet name or one-based position, and the
     name of the sheet."""
     workbook = package.read(_WORKBOOK).decode("utf-8")
     rels = package.read(_WORKBOOK_RELS).decode("utf-8")
-    targets = dict(re.findall(r'<Relationship Id="([^"]+)"[^>]*Target="([^"]+)"', rels))
-    sheets = re.findall(r'<sheet\b[^>]*name="([^"]*)"[^>]*r:id="([^"]+)"', workbook)
+    targets = _relationship_targets(rels)
+    sheets = sheet_entries(workbook)
     if not sheets:
         raise PowerQueryError("this workbook lists no worksheets")
     if isinstance(sheet, int):
@@ -306,6 +369,7 @@ def _add_table_to_sheet(
         for index, column in enumerate(columns)
     )
     raw = _write_header(raw, header, start, len(columns))
+    raw = _declare_relationship_namespace(raw)
     if "<tableParts" in raw:
         raw = re.sub(
             r'<tableParts count="(\d+)">',
@@ -321,6 +385,28 @@ def _add_table_to_sheet(
     package.write(part, raw.encode("utf-8"))
 
 
+#: The namespace a `<tablePart r:id=...>` reference lives in.
+_RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+
+
+def _declare_relationship_namespace(sheet: str) -> str:
+    """Make sure the worksheet element declares the `r:` prefix.
+
+    Excel always writes it on the root element, so the reference added
+    below resolved.  openpyxl writes the prefix only where it uses one,
+    and a worksheet with no table has no use for it, which left the
+    `r:id` added here pointing at a prefix nothing declared.  That is not
+    well-formed XML, and Excel would not open the workbook at all.
+    """
+    opening = re.search(r"<worksheet\b[^>]*>", sheet)
+    if opening is None or 'xmlns:r=' in opening.group(0):
+        return sheet
+    fixed = opening.group(0).replace(
+        "<worksheet", f'<worksheet xmlns:r="{_RELATIONSHIPS_NS}"', 1
+    )
+    return sheet.replace(opening.group(0), fixed, 1)
+
+
 def _write_header(sheet: str, cells: str, start: CellRef, width: int) -> str:
     """Put the header cells on the sheet.
 
@@ -368,17 +454,32 @@ def _widen_dimension(sheet: str, reference: str) -> str:
 
 
 def _add_defined_name(package: OpcFile, sheet_name: str, number: int, reference: str) -> None:
+    """The hidden name Excel gives an external data range.
+
+    ``localSheetId`` is the zero-based position of the sheet the name
+    belongs to among the workbook's sheets, so it has to be looked up
+    rather than assumed.  Writing a constant 0 was right only while the
+    table landed on the first sheet, and named a different sheet than the
+    reference did for any other, which Excel will not open.
+    """
+    local = sheet_index(package, sheet_name)
     raw = package.read(_WORKBOOK).decode("utf-8")
     first, last = reference.split(":")
     absolute = f"${column_letter(CellRef.parse(first).column)}${CellRef.parse(first).row}"
     absolute += f":${column_letter(CellRef.parse(last).column)}${CellRef.parse(last).row}"
     quoted = f"'{sheet_name}'" if re.search(r"[^A-Za-z0-9_]", sheet_name) else sheet_name
     defined = (
-        f'<definedName name="ExternalData_{number}" localSheetId="0" hidden="1">'
+        f'<definedName name="ExternalData_{number}" localSheetId="{local}" hidden="1">'
         f"{quoted}!{absolute}</definedName>"
     )
+    empty = re.search(r"<definedNames\s*/>", raw)
     if "<definedNames>" in raw:
         raw = raw.replace("<definedNames>", "<definedNames>" + defined)
+    elif empty is not None:
+        # An empty element written closed, which openpyxl does and Excel
+        # does not.  Appending a second block beside it puts two in the
+        # workbook, and Excel refuses that outright.
+        raw = raw.replace(empty.group(0), f"<definedNames>{defined}</definedNames>", 1)
     elif "<calcPr" in raw:
         raw = raw.replace("<calcPr", f"<definedNames>{defined}</definedNames><calcPr", 1)
     else:
@@ -407,16 +508,14 @@ def unload_from_sheet(package: OpcFile, query: str) -> bool:
         if not package.has(rels_part):
             continue
         rels = package.read(rels_part).decode("utf-8")
-        found = re.search(
-            rf'<Relationship Id="([^"]+)"[^>]*Target="\.\./tables/table{number}\.xml"[^>]*/>', rels
-        )
-        if found is None:
+        identifier = _relationship_for(rels, f"../tables/table{number}.xml")
+        if identifier is None:
             continue
         drop_relationship(package, rels_part, f"../tables/table{number}.xml")
         if "<Relationship " not in package.read(rels_part).decode("utf-8"):
             package.remove(rels_part)
         sheet = package.read(part).decode("utf-8")
-        sheet = re.sub(rf'<tablePart r:id="{found.group(1)}"\s*/>', "", sheet)
+        sheet = re.sub(rf'<tablePart\b[^>]*:id="{re.escape(identifier)}"[^>]*/>', "", sheet)
         sheet = re.sub(
             r'<tableParts count="(\d+)">',
             lambda match: f'<tableParts count="{max(int(match.group(1)) - 1, 0)}">',

{pyopenvba-5.2.0 → pyopenvba-5.2.2}/src/pyopenvba/powerquery/workbook.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 import base64
 import re
 import uuid
+import warnings
 from pathlib import Path
 from typing import ClassVar
 from xml.etree import ElementTree
@@ -564,6 +565,20 @@ class PowerQueryWorkbook:
 
     def save(self, path: str | Path | None = None) -> Path:
         out = Path(path) if path is not None else self.path
+        # A workbook Excel has recovered carries the parts it threw out
+        # under `[trash]`, and Excel will not open a package holding one.
+        # Preserving those faithfully would hand back a file that stays
+        # broken, so they go, and the caller is told.
+        dropped = self._opc.drop_reserved()
+        if dropped:
+            warnings.warn(
+                "dropped "
+                + ", ".join(repr(name) for name in dropped)
+                + ": Excel's file recovery leaves those behind and will not "
+                "open a workbook that carries them",
+                UserWarning,
+                stacklevel=2,
+            )
         raw = self.to_bytes()
         out.write_bytes(raw)
         if path is None: