vsdxkit 0.7.0__tar.gz

vsdxkit-0.7.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, Dave Howard
+Copyright (c) 2026, Firm Footing
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vsdxkit-0.7.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: vsdxkit
+Version: 0.7.0
+Summary: vsdxkit - create, edit and analyse Microsoft Visio .vsdx files, headlessly
+Author: Shaun Eccles
+Author-email: Dave Howard <dave@codypy.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/firmfooting/vsdxkit
+Project-URL: Documentation, https://firmfooting.github.io/vsdxkit/
+Project-URL: Issues, https://github.com/firmfooting/vsdxkit/issues
+Project-URL: Original project, https://github.com/dave-howard/vsdx
+Keywords: vsdx,visio,diagram,flowchart
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Jinja2>=3.1.6
+Requires-Dist: deprecation>=2.1.0
+Requires-Dist: typing-extensions>=4.4.0; python_version < "3.12"
+Dynamic: license-file
+
+# vsdxkit
+
+[![CI](https://github.com/firmfooting/vsdxkit/actions/workflows/ci.yml/badge.svg)](https://github.com/firmfooting/vsdxkit/actions/workflows/ci.yml)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://www.python.org/)
+[![BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-firmfooting.github.io-blue.svg)](https://firmfooting.github.io/vsdxkit/)
+
+Create, edit and analyse Microsoft Visio `.vsdx` files with Python. Visio is not required at runtime.
+
+> **0.x API notice.** 0.7 is the last release of the inherited API. 1.0 renames `VisioFile` to `Document` and `Container` to `SwimlaneDiagram`, splits `Connect` into an internal `ConnectionRecord` and a public `Connector`, and drops the context manager: opening closes the archive before it returns, and `save()` is the only write. The [1.0 design](https://github.com/firmfooting/vsdxkit/blob/main/.hermes/plans/2026-09-12_simplification-usability-refactor.md) lists every change, and a migration guide lands at `docs/migration-1.0.rst` with the first breaking release. Pin `vsdxkit<1` to stay on the 0.x names.
+
+The distribution is named **`vsdxkit`**. The import remains **`vsdx`**, so existing code keeps working.
+
+vsdxkit adds shape creation, Visio-faithful connectors, connector re-anchoring, cross-functional flowchart swimlanes, stricter package handling, current Python tooling and typed public APIs. It began as a fork of [`dave-howard/vsdx`](https://github.com/dave-howard/vsdx) and is now developed as its own project; see [Provenance and licence](#provenance-and-licence).
+
+## What it does
+
+- Opens, queries and edits existing `.vsdx` files without Microsoft Visio.
+- Finds shapes by ID, text, regular expression or Shape Data.
+- Creates common flowchart shapes from a bundled palette.
+- Creates dynamic or connection-point glue with straight, right-angle or curved routing.
+- Re-anchors either end of an existing connector.
+- Reads and extends Visio cross-functional flowchart swimlanes.
+- Copies shapes and pages while rewriting package-local IDs and importing masters.
+- Renders data into Visio templates with Jinja.
+- Saves to a new file or safely replaces the source file in place.
+
+The implementation edits the XML parts inside the Open Packaging Convention archive. It does not drive the Visio user interface. Generated connector and swimlane files are nevertheless checked against Microsoft Visio through COM as a release gate.
+
+## Installation
+
+`vsdxkit` is not yet published on PyPI. Install it from GitHub:
+
+```bash
+python -m pip install "vsdxkit @ git+https://github.com/firmfooting/vsdxkit.git"
+```
+
+For development:
+
+```bash
+git clone https://github.com/firmfooting/vsdxkit.git
+cd vsdxkit
+uv sync --locked
+```
+
+Python 3.10–3.14 is supported on Linux and Windows. Add `--group docs` to that
+sync if you also want to build the documentation; Sphinx needs Python 3.12 or
+later.
+
+## Open, edit and save
+
+Use the context manager to close the package cleanly. Saving is explicit.
+
+```python
+from vsdx import VisioFile
+
+with VisioFile("diagram.vsdx") as vis:
+    page = vis.pages[0]
+    shape = page.find_shape_by_text("Shape to remove")
+
+    if shape is not None:
+        shape.text = "Renamed shape"
+
+    vis.save_vsdx("edited.vsdx")
+```
+
+Call `save_vsdx()` without a filename to replace the source file in place:
+
+```python
+with VisioFile("diagram.vsdx") as vis:
+    vis.pages[0].name = "Current state"
+    vis.save_vsdx()
+```
+
+## Create shapes and connectors
+
+Shape coordinates are in Visio page units, normally inches. `x` and `y` identify the shape centre.
+
+```python
+from vsdx import VisioFile
+
+with VisioFile("diagram.vsdx") as vis:
+    page = vis.pages[0]
+
+    start = vis.create_shape(
+        page, "PALETTE_START_END", 2.0, 6.0, text="Start"
+    )
+    work = vis.create_shape(
+        page, "PALETTE_PROCESS", 6.0, 6.0, text="Do the thing"
+    )
+    decision = vis.create_shape(
+        page, "PALETTE_DECISION", 10.0, 6.0, text="OK?"
+    )
+
+    page.connect_shapes(start, work)
+    page.connect_shapes(work, decision, route="rightangle")
+    vis.save_vsdx("flow.vsdx")
+```
+
+Bundled palette names are:
+
+- `PALETTE_PROCESS`
+- `PALETTE_DECISION`
+- `PALETTE_START_END`
+- `PALETTE_PARALLELOGRAM`
+- `PALETTE_DATABASE`
+
+Connector `route` combines glue and routing behaviour:
+
+| Value | Meaning |
+|---|---|
+| `dynamic` | Dynamic shape glue. This is the default. |
+| `point` | Glue to zero-based connection points selected with `from_cp` and `to_cp`. |
+| `straight` | Dynamic glue with straight routing. |
+| `rightangle` | Dynamic glue with right-angle routing. |
+| `curved` | Dynamic glue with curved routing. |
+| `point|curved` | Connection-point glue with curved routing. |
+
+## Re-anchor a connector
+
+Pass only the end that should move. A `None` endpoint keeps the current shape.
+
+```python
+connector = page.find_shape_by_id("9")
+new_target = page.find_shape_by_text("Store")
+
+if connector is not None and new_target is not None:
+    page.reanchor_connector(connector, to_shape=new_target)
+```
+
+Deleting a shape through `page.delete_shape(shape)` also removes incident connectors and their `Connect` records.
+
+## Work with swimlanes
+
+Swimlane operations require an existing Visio cross-functional flowchart (CFF) page. `add_swimlane()` clones the current top lane and updates the CFF container geometry.
+
+```python
+with VisioFile("cross-functional-flow.vsdx") as vis:
+    page = vis.pages[0]
+    container = page.get_container()
+
+    if container is None:
+        raise ValueError("The page is not a Visio CFF diagram")
+
+    review_lane = page.add_swimlane("Review")
+    check = vis.create_shape(
+        page, "PALETTE_PROCESS", 6.0, 2.0, text="Check"
+    )
+    page.add_shape_to_lane(check, review_lane)
+
+    assert container.lane_of(check) is not None
+    vis.save_vsdx("with-review-lane.vsdx")
+```
+
+Visio CFF membership is geometric. Shapes are associated with the lane whose vertical band contains their centre; there is no separate membership field to write.
+
+## Render a Jinja template
+
+Jinja expressions can be stored in shape text and rendered into a new file:
+
+```python
+with VisioFile("template.vsdx") as vis:
+    vis.jinja_render_vsdx(
+        context={"project": "Ward refurbishment", "owner": "Facilities"}
+    )
+    vis.save_vsdx("rendered.vsdx")
+```
+
+The package also supports its existing group-shape loop and `showif` conventions. See `docs/templating.rst` and the `tests/test_jinja*.py` cases for the exact template structure.
+
+## Limits
+
+- The library starts from an existing `.vsdx`; it does not create a complete Visio document package from nothing.
+- `.vsdm` files can be read and saved, but only back to a `.vsdm` destination. The package kind is decided by the content type of `visio/document.xml`, not by the filename, so `save_vsdx()` refuses a `.vsdx` destination for a macro-enabled package and a `.vsdm` destination for one that is not — either would produce a file whose extension and `[Content_Types].xml` disagree, which Visio reports as corrupt. Stripping macros to convert a `.vsdm` into a `.vsdx` is not supported. A destination with no extension, or with an unrelated one, gets the matching Visio extension appended.
+- Swimlane creation works on existing Visio CFF diagrams. It does not convert an ordinary page into a CFF diagram.
+- Visio may recalculate layout when a generated file opens. The library writes the glue and route cells but does not reproduce Visio's entire layout engine.
+- Loading enforces package expansion limits before any archive member is read: at most 512 members, 64 MiB per member, 256 MiB total uncompressed, and a 100:1 compression ratio, plus rejection of duplicate and path-unsafe member names. A hostile or accidental archive is refused with `vsdx.PackageLimitError` instead of exhausting process memory. The defaults suit documents from unknown sources; trusted callers can relax the caps with `VisioFile(filename, limits=PackageLimits(...))` or `limits_path="vsdx.limits.json"` (same keys, JSON object).
+
+## Development and verification
+
+```bash
+uv run --no-sync python -m pytest tests -q
+uv run --no-sync ruff check vsdx tests/test_imports.py tests/test_shape_coordinates.py
+uv run --no-sync ruff format --check vsdx tests/test_imports.py tests/test_shape_coordinates.py
+uv run --no-sync pyrefly check vsdx --min-severity warn --output-format min-text
+uv run --no-sync sphinx-build -W --keep-going -b html docs docs/_build/html
+uv run --no-sync python -m build
+```
+
+The package is held at pyrefly's `strict` preset. CI tests Python 3.10–3.14 on Ubuntu and Windows. Connector and swimlane changes also run through `tools/visio_check.ps1`, which opens generated files in an invisible Microsoft Visio instance and fails on package repair or automation errors.
+
+## Documentation
+
+The Sphinx source is in [`docs/`](docs/). Build it locally with:
+
+```bash
+uv sync --locked --group docs
+uv run --no-sync python -m sphinx -W --keep-going -b html docs docs/_build/html
+```
+
+Sphinx is pinned in the `docs` dependency group, which requires Python 3.12 or
+later. The library itself still supports 3.10, so run the docs build on a 3.12+
+interpreter.
+
+## Provenance and licence
+
+vsdxkit descends from [`dave-howard/vsdx`](https://github.com/dave-howard/vsdx), originally written by Dave Howard and released under the BSD 3-Clause licence. That work is the foundation this library is built on, and its copyright notice is retained in [`LICENSE`](LICENSE) alongside our own.
+
+vsdxkit is now developed independently: it is not a downstream of that project and does not track it. The `vsdx` import namespace is kept so existing code continues to work, and the licence remains BSD 3-Clause.

vsdxkit-0.7.0/README.md

@@ -0,0 +1,209 @@
+# vsdxkit
+
+[![CI](https://github.com/firmfooting/vsdxkit/actions/workflows/ci.yml/badge.svg)](https://github.com/firmfooting/vsdxkit/actions/workflows/ci.yml)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://www.python.org/)
+[![BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-firmfooting.github.io-blue.svg)](https://firmfooting.github.io/vsdxkit/)
+
+Create, edit and analyse Microsoft Visio `.vsdx` files with Python. Visio is not required at runtime.
+
+> **0.x API notice.** 0.7 is the last release of the inherited API. 1.0 renames `VisioFile` to `Document` and `Container` to `SwimlaneDiagram`, splits `Connect` into an internal `ConnectionRecord` and a public `Connector`, and drops the context manager: opening closes the archive before it returns, and `save()` is the only write. The [1.0 design](https://github.com/firmfooting/vsdxkit/blob/main/.hermes/plans/2026-09-12_simplification-usability-refactor.md) lists every change, and a migration guide lands at `docs/migration-1.0.rst` with the first breaking release. Pin `vsdxkit<1` to stay on the 0.x names.
+
+The distribution is named **`vsdxkit`**. The import remains **`vsdx`**, so existing code keeps working.
+
+vsdxkit adds shape creation, Visio-faithful connectors, connector re-anchoring, cross-functional flowchart swimlanes, stricter package handling, current Python tooling and typed public APIs. It began as a fork of [`dave-howard/vsdx`](https://github.com/dave-howard/vsdx) and is now developed as its own project; see [Provenance and licence](#provenance-and-licence).
+
+## What it does
+
+- Opens, queries and edits existing `.vsdx` files without Microsoft Visio.
+- Finds shapes by ID, text, regular expression or Shape Data.
+- Creates common flowchart shapes from a bundled palette.
+- Creates dynamic or connection-point glue with straight, right-angle or curved routing.
+- Re-anchors either end of an existing connector.
+- Reads and extends Visio cross-functional flowchart swimlanes.
+- Copies shapes and pages while rewriting package-local IDs and importing masters.
+- Renders data into Visio templates with Jinja.
+- Saves to a new file or safely replaces the source file in place.
+
+The implementation edits the XML parts inside the Open Packaging Convention archive. It does not drive the Visio user interface. Generated connector and swimlane files are nevertheless checked against Microsoft Visio through COM as a release gate.
+
+## Installation
+
+`vsdxkit` is not yet published on PyPI. Install it from GitHub:
+
+```bash
+python -m pip install "vsdxkit @ git+https://github.com/firmfooting/vsdxkit.git"
+```
+
+For development:
+
+```bash
+git clone https://github.com/firmfooting/vsdxkit.git
+cd vsdxkit
+uv sync --locked
+```
+
+Python 3.10–3.14 is supported on Linux and Windows. Add `--group docs` to that
+sync if you also want to build the documentation; Sphinx needs Python 3.12 or
+later.
+
+## Open, edit and save
+
+Use the context manager to close the package cleanly. Saving is explicit.
+
+```python
+from vsdx import VisioFile
+
+with VisioFile("diagram.vsdx") as vis:
+    page = vis.pages[0]
+    shape = page.find_shape_by_text("Shape to remove")
+
+    if shape is not None:
+        shape.text = "Renamed shape"
+
+    vis.save_vsdx("edited.vsdx")
+```
+
+Call `save_vsdx()` without a filename to replace the source file in place:
+
+```python
+with VisioFile("diagram.vsdx") as vis:
+    vis.pages[0].name = "Current state"
+    vis.save_vsdx()
+```
+
+## Create shapes and connectors
+
+Shape coordinates are in Visio page units, normally inches. `x` and `y` identify the shape centre.
+
+```python
+from vsdx import VisioFile
+
+with VisioFile("diagram.vsdx") as vis:
+    page = vis.pages[0]
+
+    start = vis.create_shape(
+        page, "PALETTE_START_END", 2.0, 6.0, text="Start"
+    )
+    work = vis.create_shape(
+        page, "PALETTE_PROCESS", 6.0, 6.0, text="Do the thing"
+    )
+    decision = vis.create_shape(
+        page, "PALETTE_DECISION", 10.0, 6.0, text="OK?"
+    )
+
+    page.connect_shapes(start, work)
+    page.connect_shapes(work, decision, route="rightangle")
+    vis.save_vsdx("flow.vsdx")
+```
+
+Bundled palette names are:
+
+- `PALETTE_PROCESS`
+- `PALETTE_DECISION`
+- `PALETTE_START_END`
+- `PALETTE_PARALLELOGRAM`
+- `PALETTE_DATABASE`
+
+Connector `route` combines glue and routing behaviour:
+
+| Value | Meaning |
+|---|---|
+| `dynamic` | Dynamic shape glue. This is the default. |
+| `point` | Glue to zero-based connection points selected with `from_cp` and `to_cp`. |
+| `straight` | Dynamic glue with straight routing. |
+| `rightangle` | Dynamic glue with right-angle routing. |
+| `curved` | Dynamic glue with curved routing. |
+| `point|curved` | Connection-point glue with curved routing. |
+
+## Re-anchor a connector
+
+Pass only the end that should move. A `None` endpoint keeps the current shape.
+
+```python
+connector = page.find_shape_by_id("9")
+new_target = page.find_shape_by_text("Store")
+
+if connector is not None and new_target is not None:
+    page.reanchor_connector(connector, to_shape=new_target)
+```
+
+Deleting a shape through `page.delete_shape(shape)` also removes incident connectors and their `Connect` records.
+
+## Work with swimlanes
+
+Swimlane operations require an existing Visio cross-functional flowchart (CFF) page. `add_swimlane()` clones the current top lane and updates the CFF container geometry.
+
+```python
+with VisioFile("cross-functional-flow.vsdx") as vis:
+    page = vis.pages[0]
+    container = page.get_container()
+
+    if container is None:
+        raise ValueError("The page is not a Visio CFF diagram")
+
+    review_lane = page.add_swimlane("Review")
+    check = vis.create_shape(
+        page, "PALETTE_PROCESS", 6.0, 2.0, text="Check"
+    )
+    page.add_shape_to_lane(check, review_lane)
+
+    assert container.lane_of(check) is not None
+    vis.save_vsdx("with-review-lane.vsdx")
+```
+
+Visio CFF membership is geometric. Shapes are associated with the lane whose vertical band contains their centre; there is no separate membership field to write.
+
+## Render a Jinja template
+
+Jinja expressions can be stored in shape text and rendered into a new file:
+
+```python
+with VisioFile("template.vsdx") as vis:
+    vis.jinja_render_vsdx(
+        context={"project": "Ward refurbishment", "owner": "Facilities"}
+    )
+    vis.save_vsdx("rendered.vsdx")
+```
+
+The package also supports its existing group-shape loop and `showif` conventions. See `docs/templating.rst` and the `tests/test_jinja*.py` cases for the exact template structure.
+
+## Limits
+
+- The library starts from an existing `.vsdx`; it does not create a complete Visio document package from nothing.
+- `.vsdm` files can be read and saved, but only back to a `.vsdm` destination. The package kind is decided by the content type of `visio/document.xml`, not by the filename, so `save_vsdx()` refuses a `.vsdx` destination for a macro-enabled package and a `.vsdm` destination for one that is not — either would produce a file whose extension and `[Content_Types].xml` disagree, which Visio reports as corrupt. Stripping macros to convert a `.vsdm` into a `.vsdx` is not supported. A destination with no extension, or with an unrelated one, gets the matching Visio extension appended.
+- Swimlane creation works on existing Visio CFF diagrams. It does not convert an ordinary page into a CFF diagram.
+- Visio may recalculate layout when a generated file opens. The library writes the glue and route cells but does not reproduce Visio's entire layout engine.
+- Loading enforces package expansion limits before any archive member is read: at most 512 members, 64 MiB per member, 256 MiB total uncompressed, and a 100:1 compression ratio, plus rejection of duplicate and path-unsafe member names. A hostile or accidental archive is refused with `vsdx.PackageLimitError` instead of exhausting process memory. The defaults suit documents from unknown sources; trusted callers can relax the caps with `VisioFile(filename, limits=PackageLimits(...))` or `limits_path="vsdx.limits.json"` (same keys, JSON object).
+
+## Development and verification
+
+```bash
+uv run --no-sync python -m pytest tests -q
+uv run --no-sync ruff check vsdx tests/test_imports.py tests/test_shape_coordinates.py
+uv run --no-sync ruff format --check vsdx tests/test_imports.py tests/test_shape_coordinates.py
+uv run --no-sync pyrefly check vsdx --min-severity warn --output-format min-text
+uv run --no-sync sphinx-build -W --keep-going -b html docs docs/_build/html
+uv run --no-sync python -m build
+```
+
+The package is held at pyrefly's `strict` preset. CI tests Python 3.10–3.14 on Ubuntu and Windows. Connector and swimlane changes also run through `tools/visio_check.ps1`, which opens generated files in an invisible Microsoft Visio instance and fails on package repair or automation errors.
+
+## Documentation
+
+The Sphinx source is in [`docs/`](docs/). Build it locally with:
+
+```bash
+uv sync --locked --group docs
+uv run --no-sync python -m sphinx -W --keep-going -b html docs docs/_build/html
+```
+
+Sphinx is pinned in the `docs` dependency group, which requires Python 3.12 or
+later. The library itself still supports 3.10, so run the docs build on a 3.12+
+interpreter.
+
+## Provenance and licence
+
+vsdxkit descends from [`dave-howard/vsdx`](https://github.com/dave-howard/vsdx), originally written by Dave Howard and released under the BSD 3-Clause licence. That work is the foundation this library is built on, and its copyright notice is retained in [`LICENSE`](LICENSE) alongside our own.
+
+vsdxkit is now developed independently: it is not a downstream of that project and does not track it. The `vsdx` import namespace is kept so existing code continues to work, and the licence remains BSD 3-Clause.

vsdxkit-0.7.0/pyproject.toml

@@ -0,0 +1,126 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vsdxkit"
+description = "vsdxkit - create, edit and analyse Microsoft Visio .vsdx files, headlessly"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Dave Howard", email = "dave@codypy.com" },
+    { name = "Shaun Eccles" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "Jinja2>=3.1.6",
+    "deprecation>=2.1.0",
+    "typing-extensions>=4.4.0; python_version < '3.12'",
+]
+dynamic = ["version"]
+keywords = ["vsdx", "visio", "diagram", "flowchart"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/firmfooting/vsdxkit"
+Documentation = "https://firmfooting.github.io/vsdxkit/"
+Issues = "https://github.com/firmfooting/vsdxkit/issues"
+"Original project" = "https://github.com/dave-howard/vsdx"
+
+[dependency-groups]
+docs = [
+    "sphinx==9.1.0",
+    "sphinx-rtd-theme==3.1.0",
+]
+test = [
+    "pytest>=8.4.0",
+]
+lint = [
+    "ruff==0.16.7",
+    "pyrefly==1.3.0",
+    "zizmor==1.30.1",
+    "mypy>=2.3.1",
+]
+build = [
+    "build==1.6.1",
+]
+coverage = [
+    "pytest-cov>=6.2.1",
+]
+dev = [
+    { include-group = "test" },
+    { include-group = "lint" },
+    { include-group = "build" },
+    { include-group = "coverage" },
+]
+
+[tool.uv.dependency-groups]
+# Sphinx drops old interpreters faster than this library does: 9.x requires
+# 3.12 while vsdxkit itself still supports 3.10. Giving the docs group its own
+# floor keeps the universal resolution satisfiable across the whole
+# requires-python range, instead of dragging the library up to the
+# documentation toolchain's floor. Raise this together with the Python version
+# used by the CI docs build and by the Docs workflow that publishes to Pages.
+docs = { requires-python = ">=3.12" }
+
+[tool.setuptools]
+packages = ["vsdx"]
+include-package-data = false
+
+[tool.setuptools.package-data]
+vsdx = ["media/*.vsdx", "py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "vsdx.__version__" }
+
+[tool.ruff]
+line-length = 127
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+# E501 (line length) handled by formatter; docstring rules not adopted yet
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# tests use broad fixtures and long parametrise lines
+"tests/*" = ["SIM117"]
+
+[tool.pyrefly]
+project-includes = ["vsdx"]
+# strict preset: the package type-checks clean at this level, so keep it there
+preset = "strict"
+
+[tool.coverage.report]
+# fail_under compares the rounded total, so two decimal places: at the default
+# precision of 0, a threshold of 90 would really mean 89.5.
+precision = 2
+# Ratchet: this number only goes up. It is the coverage the whole suite already
+# has, so a full run below it means a change arrived untested. Raise it when
+# coverage improves; never edit it down to make a red build green. Measured
+# 2026-09-13 on CPython 3.12: 2884 statements, 283 missed (90.19%), floored to
+# a whole percent. It applies to every local `--cov` run as well, so a
+# single-file run trips it; pass `--cov-fail-under=0` there.
+fail_under = 90

vsdxkit-0.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vsdxkit-0.7.0/tests/test_add_page_at_positions.py

@@ -0,0 +1,55 @@
+"""Relative page positions must not silently append without a reference page."""
+
+import io
+import os
+import xml.etree.ElementTree as ET
+
+import pytest
+
+from vsdx import PagePosition, VisioFile
+
+basedir = os.path.dirname(os.path.realpath(__file__))
+
+
+def _pages_rels_root(visio_file):
+    """The Relationship element root of the loaded package's pages.xml.rels."""
+    for key, content in visio_file.zip_file_contents.items():
+        if key.endswith("visio/pages/_rels/pages.xml.rels"):
+            return ET.parse(io.BytesIO(content.getvalue())).getroot()
+    raise AssertionError("pages.xml.rels not found in package")
+
+
+@pytest.mark.parametrize("position", [PagePosition.BEFORE, PagePosition.AFTER])
+def test_add_page_at_rejects_relative_position_without_reference_page(vsdx_copy, tmp_path, position):
+    path = os.path.join(basedir, "test1.vsdx")
+    copy_path = vsdx_copy("test1.vsdx")
+    output = os.path.join(str(tmp_path), "out.vsdx")
+    with VisioFile(path) as reference:
+        names_before = [p.name for p in reference.pages]
+        reference_rels = [rel for rel in _pages_rels_root(reference) if "page" in rel.attrib.get("Target", "")]
+    with VisioFile(copy_path) as vis:
+        with pytest.raises(ValueError, match="requires a reference page"):
+            vis.add_page_at(position, "new")
+        assert [p.name for p in vis.pages] == names_before  # nothing appended
+        vis.save_vsdx(output)  # a rejected call must leave nothing to persist
+
+    with VisioFile(output) as reloaded:
+        assert [p.name for p in reloaded.pages] == names_before
+        page_rels = [rel for rel in _pages_rels_root(reloaded) if "page" in rel.attrib.get("Target", "")]
+        assert len(page_rels) == len(reference_rels)  # no dangling relationship
+
+
+def test_add_page_at_integer_and_relative_positions_place_correctly(vsdx_copy):
+    path = vsdx_copy("test1.vsdx")
+    with VisioFile(path) as vis:
+        first = vis.add_page_at(PagePosition.FIRST, "first-added")
+        assert vis.pages.index(first) == 0
+
+        at_one = vis.add_page_at(1, "at-one")
+        assert vis.pages.index(at_one) == 1
+
+        last = vis.add_page_at(PagePosition.LAST, "last-added")
+        assert vis.pages.index(last) == len(vis.pages) - 1
+
+        appended = vis.add_page("appended")
+        assert vis.pages.index(appended) == len(vis.pages) - 1