swdesigntables 0.1.0__tar.gz

swdesigntables-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: release
+
+# Publishes to PyPI when a v* tag is pushed, using Trusted Publishing.
+# No API token is stored anywhere: PyPI verifies the workflow's OIDC identity.
+#
+# One-time setup on PyPI (Publishing -> Add a new pending publisher):
+#   owner/repository: ivanperezdesigner/swdesigntables
+#   workflow:         release.yml
+#   environment:      pypi
+# and create the `pypi` environment under Settings -> Environments here.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Check the tag matches __version__
+        # Publishing v0.2.0 from a 0.1.0 source is the classic own goal.
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(python -c "import re,pathlib; print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('src/swdesigntables/__init__.py').read_text()).group(1))")
+          echo "tag=$TAG source=$VERSION"
+          test "$TAG" = "$VERSION"
+
+      - name: Build
+        run: python -m build
+
+      - name: Check metadata
+        run: python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

swdesigntables-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Type check
+        run: python -m mypy
+
+      - name: Test
+        run: python -m pytest -q

swdesigntables-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Build artefacts
+dist/
+build/
+*.egg-info/
+
+# Environments
+venv/
+.venv/
+
+# Caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Generated tables from manual runs
+*.xlsx

swdesigntables-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-11
+
+First release.
+
+### Added
+
+- `DesignTable`: title cell, headers from B2, the `Family` defined name, and
+  configuration rows addressed by column identity rather than column number.
+- A parameter catalogue with typed factories for `dimension`, `global_variable`,
+  `state`, `prop`, `description`, `parent`, `display_state`, `component_config`,
+  `component_state`, `component_visibility`, `component_fixed`,
+  `component_display_state`, `comment`, `color`, `part_number`, `user_notes`,
+  `never_expand_in_bom`, `suppress_new_features`, `suppress_new_components`,
+  `sw_property` and `tolerance`.
+- A verification `Status` on every parameter, and an `unverified-parameter`
+  warning for anything not confirmed against a real model.
+- `register_parameter()` and `raw()` so no header is out of reach.
+- `parse_header()`, which turns an existing header string into its typed column,
+  for migrating scripts that already hold a list of header strings.
+- `TableTemplate` and `blank_table()` for reusable bases and empty skeletons.
+- Value types `State`, `ComponentState`, `YesNo` and `Expression`, with
+  `StateFormat.NUMERIC` for tables that spell suppression `1`/`0`.
+- Validation with stable issue codes, three levels of strictness, and per-code
+  suppression.
+- Extra sheets, optionally hidden, plus extra workbook defined names. `_SWX`,
+  `Family` and `_SWX_0` are reserved.
+- Deterministic output: fixed document timestamps, so a regenerated table only
+  differs in git when it actually changed.
+
+### Known limitations
+
+- Roughly half the catalogue is marked `DOCUMENTED` rather than `VERIFIED`: the
+  syntax comes from documentation but has not been watched working in
+  SOLIDWORKS. See the README for the Auto-create recipe that confirms one.
+- Sheet metal parameters (`$SM-…`) are not shipped, because no reliable source
+  confirmed their syntax. Use `raw()` or `register_parameter()`.
+- The spelling of `$USER_NOTES` and `$NEVER_EXPAND_IN_BOM` is uncertain; sources
+  disagree on hyphens versus underscores. Both are single constants in
+  `Vocabulary`.
+- Write only. No reading of existing tables, no COM integration, no CLI.
+
+[Unreleased]: https://github.com/ivanperezdesigner/swdesigntables/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ivanperezdesigner/swdesigntables/releases/tag/v0.1.0

swdesigntables-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swdesigntables-0.1.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.5
+Name: swdesigntables
+Version: 0.1.0
+Summary: Build SOLIDWORKS design tables from Python, with typed headers and validation.
+Project-URL: Homepage, https://github.com/ivanperezdesigner/swdesigntables
+Project-URL: Issues, https://github.com/ivanperezdesigner/swdesigntables/issues
+Project-URL: Changelog, https://github.com/ivanperezdesigner/swdesigntables/blob/main/CHANGELOG.md
+Author: Ivan Perez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cad,configurations,design table,openpyxl,solidworks,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+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: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: openpyxl<4,>=3.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Requires-Dist: types-openpyxl; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# swdesigntables
+
+Build SOLIDWORKS design tables from Python, with typed headers instead of
+hand-typed strings.
+
+A design table is an Excel sheet embedded in a SOLIDWORKS model: each row makes
+a configuration, each column drives a parameter. The format has a handful of
+load-bearing details that are easy to get wrong and that fail *silently* — the
+table inserts, nothing changes, and you go looking at the model. This package
+writes those details for you and warns about the rest.
+
+```bash
+pip install swdesigntables
+```
+
+Only dependency: `openpyxl`. Pure Python, no SOLIDWORKS install needed to
+generate a file.
+
+## Quickstart
+
+```python
+import swdesigntables as sw
+
+length = sw.dimension("Length", "Boss-Extrude1")
+holes = sw.state("HolePattern")
+material = sw.prop("Material")
+
+table = sw.DesignTable("BRK-MASTER", [length, holes, material])
+table.add_configuration(
+    "BRK-025",
+    {length: 25.0, holes: sw.SUPPRESSED, material: "6061-T6"},
+    description="Short bracket",
+)
+table.add_configuration(
+    "BRK-040",
+    {length: 40.0, holes: sw.UNSUPPRESSED, material: "6061-T6"},
+    description="Long bracket",
+)
+
+table.save("brk_master_dt.xlsx")
+```
+
+Insert the result with **Insert → Tables → Design Table → From file**.
+
+## What it gets right so you do not have to
+
+| Detail | Why it matters |
+|---|---|
+| `Design Table for: <model>` in A1 | The title cell SOLIDWORKS expects |
+| Headers start in **B2**, A2 stays empty | Writing from A2 shifts every value one column left |
+| Workbook-level defined name `Family` → `Sheet1!$A$2` | Without it SOLIDWORKS cannot find the table at all |
+| Equation values written as literal text | `cell = "=W/2"` becomes an Excel *formula* with no cached result, and SOLIDWORKS reads an empty parameter |
+| Fixed document timestamps | Two identical runs produce identical bytes, so git shows a change only when the table really changed |
+| Numeric-looking strings stay strings | A part number of `0012` does not come back as `12` |
+
+## Values are addressed by identity, never by column number
+
+```python
+length = table.add_column(sw.dimension("Length", "Boss-Extrude1"))
+table.add_configuration("A", {length: 25.0})
+```
+
+You cannot pass a positional row. That is deliberate: mixing a
+header-to-index map with literal column numbers is how a table silently starts
+writing the wrong values after someone inserts a column in the middle.
+
+Supplying a value for a column that was never declared is always an error, so
+a typo loses nothing quietly.
+
+## The parameter catalogue
+
+Every parameter carries a **verification status**, readable at runtime via
+`column.status` and listed by `sw.list_parameters()`.
+
+- **`VERIFIED`** — confirmed against real design table files.
+- **`DOCUMENTED`** — described by SOLIDWORKS documentation, not confirmed here
+  against a live model. Using one emits an `unverified-parameter` warning.
+- **`UNVERIFIED`** — registered at runtime by you, or otherwise unconfirmed.
+
+This distinction is not decoration. Half of the catalogue below has not been
+watched working in SOLIDWORKS by the author, and saying so is more useful than
+implying a certainty that is not there.
+
+### Verified
+
+| Factory | Header | Values |
+|---|---|---|
+| `dimension("Length", "Boss-Extrude1")` | `Length@Boss-Extrude1` | number |
+| `global_variable("width")` | `$VALUE@width@Equations` | number or `Expression` |
+| `state("Draft2")` | `$STATE@Draft2` | `State.SUPPRESSED` / `State.UNSUPPRESSED` |
+| `prop("Material")` | `$PRP@Material` | text or number |
+| `component_config("Arm", 1)` | `$CONFIGURATION@Arm<1>` | configuration name |
+| `description()` | `$DESCRIPTION` | text |
+| `parent()` | `$PARENT` | configuration name |
+| `display_state()` | `$DISPLAYSTATE` | name |
+
+### Documented, not verified here
+
+| Factory | Header | Values |
+|---|---|---|
+| `comment()` | `$COMMENT` | text; SOLIDWORKS ignores it |
+| `color()` | `$COLOR` | 32-bit RGB integer |
+| `part_number()` | `$PARTNUMBER` | text |
+| `user_notes()` | `$USER_NOTES` | text |
+| `never_expand_in_bom()` | `$NEVER_EXPAND_IN_BOM` | `YesNo` |
+| `tolerance("D1", "Sketch1")` | `$TOLERANCE@D1@Sketch1` | tolerance spec |
+| `component_state("Screw", 2)` | `$STATE@Screw<2>` | `ComponentState` (`S`/`R`) |
+| `component_visibility("Screw", 2)` | `$SHOW@Screw<2>` | `YesNo` |
+| `component_fixed("Screw", 2)` | `$FIXED@Screw<2>` | `YesNo` |
+| `component_display_state("Screw", 2)` | `$DISPLAYSTATE@Screw<2>` | name |
+| `suppress_new_features()` | `$SUPPRESS NEW FEATURES` | `YesNo` |
+| `suppress_new_components()` | `$SUPPRESS NEW COMPONENTS` | `YesNo` |
+| `sw_property("Mass")` | `$SW-Mass` | read-only |
+
+Two spellings are genuinely uncertain because sources disagree on punctuation:
+`$USER_NOTES` vs `$USERNOTES`, and `$NEVER_EXPAND_IN_BOM` vs
+`$NEVER-EXPAND-IN-BOM`. Header syntax is case insensitive in SOLIDWORKS, but
+that does not extend to hyphens and underscores. Both live as single constants
+in `Vocabulary`, so correcting one is a one-line change.
+
+**Sheet metal (`$SM-…`) is deliberately absent.** No reliable source confirmed
+its syntax, and shipping an invented factory is worse than shipping none. Use
+`raw()` or `register_parameter()`.
+
+### Confirming a parameter yourself
+
+The syntax is not worth guessing at. On a **copy** of the model:
+
+1. **Insert → Tables → Design Table → Auto-create**
+2. SOLIDWORKS opens an embedded sheet with the header row it proposes
+3. Copy that row, close without saving, delete the copy
+
+A minute of checking beats an afternoon of columns the model ignores.
+
+### Nothing is out of reach
+
+```python
+sw.raw("$WHATEVER@Thing<3>")          # any header at all, unchecked
+
+sw.register_parameter(                # a new typed factory, at runtime
+    "sheet_metal_thickness",
+    template="$SM-THICKNESS",
+    summary="Sheet metal thickness.",
+    value_kind=sw.ValueKind.NUMBER,
+)
+sw.column("sheet_metal_thickness")
+```
+
+## Reusable bases
+
+`TableTemplate` holds everything that does not change row to row — model, output
+directory, file name, columns, naming rule — so every script in a project starts
+from the same base.
+
+```python
+from pathlib import Path
+import swdesigntables as sw
+
+BRACKET = sw.TableTemplate(
+    model_name="BRK-MASTER",
+    output_dir=Path("tables"),
+    file_name="brk_master_dt.xlsx",
+    columns=(length, width, sw.description()),
+    config_name=lambda width, length: f"BRK-{width:03d}-{length:03d}",
+    round_floats=3,
+)
+
+table = BRACKET.new_table()
+table.add_configuration(BRACKET.name_for(width=25, length=40), {...})
+table.save()                      # goes to tables/brk_master_dt.xlsx
+```
+
+It is frozen; `BRACKET.replace(model_name="BRK-HEAVY")` gives you a variant
+without disturbing the original.
+
+To start from an empty but valid file:
+
+```python
+sw.blank_table("BRK-MASTER", [length, width], path="skeleton.xlsx")
+```
+
+That is also the cheapest way to find out whether SOLIDWORKS accepts a set of
+headers: generate the skeleton, insert it with **From file**, and see what it
+says before writing a generator around it.
+
+## Suppression: `S`/`U` or `1`/`0`
+
+Documentation describes `S` and `U`. Working tables in the wild use `1` and `0`.
+Both are supported and neither is silently rewritten:
+
+```python
+sw.DesignTable(..., state_format=sw.StateFormat.NUMERIC)   # writes 1 / 0
+sw.State.from_legacy_int(1)                                # -> State.SUPPRESSED
+```
+
+Component suppression is a different vocabulary — `ComponentState` is `S`/`R`,
+where `R` is Resolved — and mixing them up is caught.
+
+## Migrating a script that already has header strings
+
+`parse_header` turns an existing header string into the typed column that
+renders it, so a list you already have keeps working:
+
+```python
+table = sw.DesignTable(
+    "Extrusion Profile",
+    columns=[sw.parse_header(h) for h in HEADERS],
+    state_format=sw.StateFormat.NUMERIC,
+)
+```
+
+Anything unrecognized becomes a `raw()` column rather than an error.
+
+## Validation
+
+```python
+report = table.validate()
+for issue in report.issues:
+    print(issue)
+```
+
+Issue codes are stable across releases; message wording is not, so match on the
+code. Errors stop the write, warnings do not.
+
+A selection of what is caught: duplicate columns and configurations,
+configuration names containing `/ \ : * ? " < > |`, values for undeclared
+columns, `$PARENT` cycles and children placed before their parent, the reserved
+`_SWX` sheet name, a state letter in a numeric column, and
+`equations-dimension-conflict` — driving both a dimension and a global variable
+of the same name, which usually means someone expected the dimension column to
+win an argument it cannot win.
+
+Three levels of strictness:
+
+```python
+sw.DesignTable(...)                              # errors raise, warnings warn
+sw.DesignTable(..., strict=False)                # everything degrades to a warning
+sw.DesignTable(..., ignore=("float-precision",)) # silence one code
+```
+
+In CI, promote warnings so they cannot rot:
+
+```bash
+python -W error::swdesigntables.errors.DesignTableWarning build_tables.py
+```
+
+### What validation cannot do
+
+Without a live model there is nothing to check names against. A misspelled
+feature name still produces a column SOLIDWORKS silently ignores. This package
+only catches problems of *shape* — stray whitespace, an embedded `@`, a value of
+the wrong kind. Claiming more is how people learn to stop reading warnings.
+
+## Extra sheets, and why `_SWX` is refused
+
+You can add your own sheets — source data, notes, a parameter legend — and hide
+them:
+
+```python
+table.add_sheet("Notes", [["Source"], ["main_db.xlsx"]], hidden=True)
+table.add_defined_name("Lengths", "Sheet1!$B$3:$B$50")
+```
+
+`Sheet1` always stays first and visible. Hidden means `hidden`, never
+`veryHidden`, so you can unhide it in Excel when something misbehaves.
+
+**`_SWX` is rejected.** When SOLIDWORKS embeds a design table it creates a
+hidden `_SWX` sheet and a `_SWX_0` defined name of its own. Authoring them here
+produces a table SOLIDWORKS cannot reconcile. Likewise `Family` is created
+automatically and adding it by hand is an error.
+
+## Design tables are not the source of truth
+
+When a table is generated by a script it stays an internal detail of the
+generator. The source of truth is what lives outside: a database, a spreadsheet,
+a configuration file. If the embedded table becomes the source, no other process
+can read the data without opening SOLIDWORKS.
+
+```
+external source -> rules -> design table -> configurations
+```
+
+## Preparing the master model
+
+The table can only be as good as the model underneath it:
+
+1. **Name your dimensions.** Without a name they stay `D1@Sketch1`, and in three
+   weeks nobody knows which is which.
+2. **Name the features you intend to suppress.** `$STATE@Cut-Extrude7` breaks
+   the moment someone reorders the tree.
+3. **One brain only.** Equations or the table, not both governing the same thing.
+   A dimension driven by an equation cannot be driven by the table — drive the
+   global variable instead.
+4. **Set document units to at least 2 decimals.** At 0 decimals a radius of 2.4
+   shows as `2`, in the model and on the drawing.
+5. **Name the model after the family, not a variant.** Rename *before* creating
+   drawings or assemblies, or you break the references.
+6. **Model the full case and suppress downwards.** Removing is easier than
+   creating.
+
+## License
+
+MIT.