pyOpenVBA 5.2.1__tar.gz → 5.2.3__tar.gz

{pyopenvba-5.2.1 → pyopenvba-5.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyOpenVBA
-Version: 5.2.1
+Version: 5.2.3
 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

{pyopenvba-5.2.1 → pyopenvba-5.2.3}/docs/power_query.md

@@ -221,6 +221,25 @@ 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 three rules of its own, and each was learned the
+hard way:
+
+* **`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 a one-sheet file cannot show.
+* **A sheet name inside a reference is quoted unless it is a plain
+  identifier**, and an apostrophe within it is doubled: `It's` is spelled
+  `'It''s'`. A single apostrophe closes the quoting early and the
+  reference names something else. A name opening with a digit is quoted
+  too, since unquoted it reads as part of a cell reference.
+* **A sheet name is stored XML-escaped**, so `A & B` sits in the file as
+  `A & B`. Reading the stored form as if it were the name meant that
+  asking for the sheet by the name it actually has found nothing.
+  Attribute values are decoded on the way in and escaped again on the way
+  out.
+
 ### Refresh control
 
 The boxes in Excel's Connection Properties dialog belong to that

{pyopenvba-5.2.1 → pyopenvba-5.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyOpenVBA"
-version = "5.2.1"
+version = "5.2.3"
 description = "Read and write VBA macros and Excel Power Query in pure Python, no dependencies."
 readme = "README.md"
 license = { text = "MIT" }

{pyopenvba-5.2.1 → pyopenvba-5.2.3}/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.1"
+__version__ = "5.2.3"

{pyopenvba-5.2.1 → pyopenvba-5.2.3}/src/pyopenvba/powerquery/_sheets.py

@@ -84,6 +84,28 @@ def _escape(value: str) -> str:
     )
 
 
+_ENTITIES = {"amp": "&", "lt": "<", "gt": ">", "quot": '"', "apos": "'"}
+
+
+def _unescape(value: str) -> str:
+    """The characters an XML attribute's stored text stands for.
+
+    A sheet named ``A & B`` is stored as ``A &amp; B``, and reading the
+    stored form as if it were the name meant that asking for the sheet by
+    the name it actually has found nothing.
+    """
+
+    def replace(match: re.Match[str]) -> str:
+        body = match.group(1)
+        if body[:2] in {"#x", "#X"}:
+            return chr(int(body[2:], 16))
+        if body.startswith("#"):
+            return chr(int(body[1:]))
+        return _ENTITIES.get(body, match.group(0))
+
+    return re.sub(r"&(#[0-9]+|#[xX][0-9a-fA-F]+|[A-Za-z]+);", replace, value)
+
+
 def _next_relationship(rels: str) -> str:
     used = {int(number) for number in re.findall(r'Id="rId(\d+)"', rels)}
     index = 1
@@ -109,8 +131,15 @@ def _attributes(element: str) -> dict[str, str]:
     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.
+
+    Values come back as the characters they stand for, not as stored, so
+    a caller comparing one against a name a user typed compares like with
+    like.
     """
-    return dict(re.findall(r'([\w.:-]+)\s*=\s*"([^"]*)"', element))
+    return {
+        key: _unescape(value)
+        for key, value in re.findall(r'([\w.:-]+)\s*=\s*"([^"]*)"', element)
+    }
 
 
 def _relationship_targets(rels: str) -> dict[str, str]:
@@ -169,13 +198,15 @@ def drop_content_type(package: OpcFile, part: str) -> None:
     )
 
 
-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 = _relationship_targets(rels)
-    sheets: list[tuple[str, str]] = []
+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
@@ -184,7 +215,27 @@ def sheet_part(package: OpcFile, sheet: str | int) -> tuple[str, str]:
             (value for key, value in attributes.items() if key.endswith(":id")), None
         )
         if "name" in attributes and identifier:
-            sheets.append((attributes["name"], 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 = _relationship_targets(rels)
+    sheets = sheet_entries(workbook)
     if not sheets:
         raise PowerQueryError("this workbook lists no worksheets")
     if isinstance(sheet, int):
@@ -419,27 +470,61 @@ def _write_header(sheet: str, cells: str, start: CellRef, width: int) -> str:
 
 
 def _widen_dimension(sheet: str, reference: str) -> str:
-    match = re.search(r'<dimension ref="([^"]*)"/>', sheet)
+    """Grow the sheet's declared extent to cover the range just written.
+
+    The element is matched by name rather than by its exact spelling: it
+    may carry other attributes, and a writer is free to put a space
+    before the closing slash, which openpyxl does.  Insisting on Excel's
+    spelling left the extent saying the sheet ended where it did before
+    the table was written.
+    """
+    match = re.search(r"<dimension\b[^>]*/>", sheet)
     if match is None:
         return sheet
+    current = _attributes(match.group(0)).get("ref")
+    if current is None:
+        return sheet
     wanted = [CellRef.parse(part) for part in reference.split(":")]
-    have = [CellRef.parse(part) for part in match.group(1).split(":")]
+    have = [CellRef.parse(part) for part in current.split(":")]
     if len(have) == 1:
         have = [have[0], have[0]]
     first = CellRef(min(have[0].column, wanted[0].column), min(have[0].row, wanted[0].row))
     last = CellRef(max(have[1].column, wanted[1].column), max(have[1].row, wanted[1].row))
-    return sheet.replace(match.group(0), f'<dimension ref="{first}:{last}"/>')
+    widened = match.group(0).replace(f'ref="{current}"', f'ref="{first}:{last}"', 1)
+    return sheet.replace(match.group(0), widened, 1)
+
+
+def quote_sheet(name: str) -> str:
+    """A sheet's name as a formula reference spells it.
+
+    Anything but a plain identifier is wrapped in apostrophes, and an
+    apostrophe inside the name is doubled, because a single one would
+    close the quoting early and leave a reference to something else.  A
+    name opening with a digit is quoted too: unquoted it reads as part of
+    a cell reference.
+    """
+    if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+        return name
+    return "'" + name.replace("'", "''") + "'"
 
 
 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"{quoted}!{absolute}</definedName>"
+        f'<definedName name="ExternalData_{number}" localSheetId="{local}" hidden="1">'
+        f"{_escape(quote_sheet(sheet_name))}!{absolute}</definedName>"
     )
     empty = re.search(r"<definedNames\s*/>", raw)
     if "<definedNames>" in raw: