modm-pinout 1.0.0__tar.gz

modm_pinout-1.0.0/.github/workflows/pypi.yaml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/modm-pinout
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install release tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine setuptools-scm[toml]
+
+      - name: Package library
+        run: |
+          python -m build
+          twine check dist/*
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

modm_pinout-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+build*
+.venv/
+dist/
+*.egg-info/

modm_pinout-1.0.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, Niklas Hauser
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of [project] 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.

modm_pinout-1.0.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: modm-pinout
+Version: 1.0.0
+Summary: Static pin mapping site generator for modm device definitions
+Keywords: embedded,modm,pinout,generator,static-site
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Requires-Dist: modm-devices>=0.13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: setuptools-scm[toml]>=8; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# modm-pinout
+
+`modm-pinout` builds a static pin-mapping site from device definitions provided by `modm-devices`.
+
+The generated output contains:
+
+- one HTML page per device
+- shared CSS and JavaScript assets
+- shared JSON datasets grouped by source XML
+- an index page for device lookup
+- a manifest describing generated pages and datasets
+
+The package installs a CLI named `modm_pinout`.
+
+> Please note that this code was vibe-coded, since we're not good at web development.
+> `modm-devices` is still written by humans though and it shows lol.
+
+## Installation
+
+```bash
+python -m pip install modm-pinout
+```
+
+For local development:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+## Usage
+
+Generate one device page:
+
+```bash
+modm_pinout stm32c011f4p6 -o build
+```
+
+Generate all supported devices:
+
+```bash
+modm_pinout --all -o build
+```
+
+## Output Layout
+
+The generated site uses this structure:
+
+```text
+build/
+  index.html
+  manifest.json
+  assets/
+  data/
+  devices/
+```
+
+## Notes
+
+- Device metadata and XML inputs are loaded from the installed `modm-devices` package.
+- Templates and frontend assets are bundled as package data inside `modm_pinout`.
+- The package and CLI naming are generic so additional device families can be integrated later.

modm_pinout-1.0.0/README.md

@@ -0,0 +1,63 @@
+# modm-pinout
+
+`modm-pinout` builds a static pin-mapping site from device definitions provided by `modm-devices`.
+
+The generated output contains:
+
+- one HTML page per device
+- shared CSS and JavaScript assets
+- shared JSON datasets grouped by source XML
+- an index page for device lookup
+- a manifest describing generated pages and datasets
+
+The package installs a CLI named `modm_pinout`.
+
+> Please note that this code was vibe-coded, since we're not good at web development.
+> `modm-devices` is still written by humans though and it shows lol.
+
+## Installation
+
+```bash
+python -m pip install modm-pinout
+```
+
+For local development:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+## Usage
+
+Generate one device page:
+
+```bash
+modm_pinout stm32c011f4p6 -o build
+```
+
+Generate all supported devices:
+
+```bash
+modm_pinout --all -o build
+```
+
+## Output Layout
+
+The generated site uses this structure:
+
+```text
+build/
+  index.html
+  manifest.json
+  assets/
+  data/
+  devices/
+```
+
+## Notes
+
+- Device metadata and XML inputs are loaded from the installed `modm-devices` package.
+- Templates and frontend assets are bundled as package data inside `modm_pinout`.
+- The package and CLI naming are generic so additional device families can be integrated later.

modm_pinout-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=69", "setuptools-scm[toml]>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "modm-pinout"
+dynamic = ["version"]
+description = "Static pin mapping site generator for modm device definitions"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["embedded", "modm", "pinout", "generator", "static-site"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = [
+  "jinja2>=3.1",
+  "modm-devices>=0.13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "setuptools-scm[toml]>=8",
+  "twine>=5.0",
+]
+
+[project.scripts]
+modm_pinout = "modm_pinout:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+modm_pinout = [
+  "assets/scripts/*.js",
+  "assets/styles/*.css",
+  "templates/*.j2",
+]
+
+[tool.setuptools_scm]
+version_scheme = "no-guess-dev"
+local_scheme = "no-local-version"
+tag_regex = "^(?:v)?(?P<version>.+)$"

modm_pinout-1.0.0/setup.cfg

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

modm_pinout-1.0.0/src/modm_pinout/__init__.py

@@ -0,0 +1,5 @@
+"""modm pinout static site builder."""
+
+from .builder import build_all_devices, build_single_device, main
+
+__all__ = ["build_all_devices", "build_single_device", "main"]

modm_pinout-1.0.0/src/modm_pinout/__main__.py

@@ -0,0 +1,11 @@
+"""Module entrypoint for the modm pinout static site builder."""
+
+from __future__ import annotations
+
+import sys
+
+from .builder import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modm_pinout-1.0.0/src/modm_pinout/assets/scripts/pinout-app.js

@@ -0,0 +1,22 @@
+"use strict";
+
+window.initializeModmPinoutApp = function initializeModmPinoutApp(config) {
+  const api = window.ModmPinout || {};
+  if (typeof api.createContext !== "function") {
+    throw new Error("Pin matrix core module did not load.");
+  }
+
+  const ctx = api.createContext(config);
+  api.attachCore(ctx);
+  api.attachPersistence(ctx);
+  api.attachRegex(ctx);
+  api.attachImportExport(ctx);
+  api.attachTable(ctx);
+  api.attachPackage(ctx);
+
+  ctx.bindPageEventHandlers();
+  ctx.renderPackageDiagram();
+  ctx.initializeWithRecovery().catch((error) => {
+    ctx.setStatus(`Failed to initialize table: ${String(error)}`, true);
+  });
+};

modm_pinout-1.0.0/src/modm_pinout/assets/scripts/pinout-core.js

@@ -0,0 +1,328 @@
+"use strict";
+
+(function registerModmPinoutCore(global) {
+  const api = global.ModmPinout = global.ModmPinout || {};
+
+  api.createContext = function createContext(config) {
+    const deviceData = config && config.deviceData ? config.deviceData : null;
+    const cookieKey = config && typeof config.cookieKey === "string" ? config.cookieKey : "";
+
+    if (!deviceData || typeof deviceData !== "object") {
+      throw new Error("Missing device data.");
+    }
+    if (!cookieKey) {
+      throw new Error("Missing cookie key.");
+    }
+
+    return {
+      DEVICE_DATA: deviceData,
+      COOKIE_KEY: cookieKey,
+      SAVE_DAYS: 365,
+      COOKIE_MAX_VALUE_BYTES: 3800,
+      SHARE_URL_PARAM: "share",
+      SHARE_URL_FORMAT: "modm-pinout-share",
+      SHARE_URL_VERSION: 1,
+      ADD_REGEX_FIELD: "__add_regex__",
+      BASE_REGEX_FILTER_FIELDS: ["position", "short_name", "selected_function", "internal_name"],
+      table: null,
+      saveTimer: null,
+      htmlDecodeNode: null,
+      textMeasureCtx: null,
+      state: {
+        selectedByRowId: {},
+        namesByRowId: {},
+        baseFilterPatterns: {},
+        reviewByRowId: {},
+        unmappedRows: [],
+        regexColumns: [],
+        nextRegexId: 1,
+      },
+    };
+  };
+
+  api.attachCore = function attachCore(ctx) {
+    const state = ctx.state;
+
+    ctx.escapeHtml = function escapeHtml(value) {
+      return String(value)
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+    };
+
+    ctx.setStatus = function setStatus(message, isError = false) {
+      const node = document.getElementById("save-status");
+      node.textContent = message;
+      node.classList.toggle("error", isError);
+    };
+
+    ctx.debounce = function debounce(fn, waitMs) {
+      return function debounced(...args) {
+        if (ctx.saveTimer !== null) {
+          window.clearTimeout(ctx.saveTimer);
+        }
+        ctx.saveTimer = window.setTimeout(() => fn(...args), waitMs);
+      };
+    };
+
+    ctx.normalizeRegexColumn = function normalizeRegexColumn(meta) {
+      if (!meta || typeof meta !== "object") {
+        return null;
+      }
+      const id = Number(meta.id);
+      if (!Number.isInteger(id) || id <= 0) {
+        return null;
+      }
+      const title = typeof meta.title === "string" && meta.title.trim()
+        ? meta.title.trim()
+        : `Regex ${id}`;
+      const pattern = typeof meta.pattern === "string" ? meta.pattern : "";
+      return {
+        id,
+        field: `regex_${id}`,
+        title,
+        pattern,
+      };
+    };
+
+    ctx.normalizeSelectedFunctionList = function normalizeSelectedFunctionList(value, availableFunctions = null) {
+      const allowedSet = Array.isArray(availableFunctions) ? new Set(availableFunctions) : null;
+      const rawValues = Array.isArray(value)
+        ? value
+        : (typeof value === "string" || typeof value === "number" ? [value] : []);
+
+      const normalized = [];
+      const seen = new Set();
+      for (const entry of rawValues) {
+        const item = String(entry ?? "").trim();
+        if (!item || seen.has(item)) {
+          continue;
+        }
+        if (allowedSet && !allowedSet.has(item)) {
+          continue;
+        }
+
+        seen.add(item);
+        normalized.push(item);
+      }
+
+      return normalized;
+    };
+
+    ctx.renderSelectedFunctionsHtml = function renderSelectedFunctionsHtml(value) {
+      const selected = ctx.normalizeSelectedFunctionList(value);
+      return selected.map((fn) => ctx.escapeHtml(fn)).join("<br>");
+    };
+
+    ctx.decodeHtmlText = function decodeHtmlText(value) {
+      const text = String(value || "");
+      if (!text || text.indexOf("&") < 0) {
+        return text;
+      }
+
+      if (!ctx.htmlDecodeNode) {
+        ctx.htmlDecodeNode = document.createElement("textarea");
+      }
+      ctx.htmlDecodeNode.innerHTML = text;
+      return ctx.htmlDecodeNode.value;
+    };
+
+    ctx.valueToSortableText = function valueToSortableText(value) {
+      if (Array.isArray(value)) {
+        return ctx.normalizeSelectedFunctionList(value).join("\n");
+      }
+
+      if (value == null) {
+        return "";
+      }
+
+      const withBreaks = String(value).replace(/<br\s*\/?>/gi, "\n");
+      const withoutTags = withBreaks.replace(/<[^>]*>/g, "");
+      return ctx.decodeHtmlText(withoutTags).trim();
+    };
+
+    ctx.compareNaturalText = function compareNaturalText(left, right) {
+      return String(left || "").localeCompare(String(right || ""), undefined, {
+        numeric: true,
+        sensitivity: "base",
+      });
+    };
+
+    ctx.displayedTextSorter = function displayedTextSorter(a, b) {
+      return ctx.compareNaturalText(ctx.valueToSortableText(a), ctx.valueToSortableText(b));
+    };
+
+    ctx.pinSorter = function pinSorter(a, b) {
+      const left = String(a || "").trim();
+      const right = String(b || "").trim();
+      const leftIsInt = /^\d+$/.test(left);
+      const rightIsInt = /^\d+$/.test(right);
+
+      if (leftIsInt && rightIsInt) {
+        return Number(left) - Number(right);
+      }
+      if (leftIsInt) {
+        return -1;
+      }
+      if (rightIsInt) {
+        return 1;
+      }
+
+      return ctx.compareNaturalText(left, right);
+    };
+
+    ctx.compareRowIdValues = function compareRowIdValues(left, right) {
+      const leftRaw = String(left ?? "");
+      const rightRaw = String(right ?? "");
+      const leftNum = Number(leftRaw);
+      const rightNum = Number(rightRaw);
+      const leftIsNumeric = Number.isFinite(leftNum) && leftRaw.trim() !== "";
+      const rightIsNumeric = Number.isFinite(rightNum) && rightRaw.trim() !== "";
+
+      if (leftIsNumeric && rightIsNumeric) {
+        return leftNum - rightNum;
+      }
+      if (leftIsNumeric) {
+        return -1;
+      }
+      if (rightIsNumeric) {
+        return 1;
+      }
+
+      return ctx.compareNaturalText(leftRaw, rightRaw);
+    };
+
+    ctx.normalizePinNameKey = function normalizePinNameKey(value) {
+      return String(value ?? "").trim().toUpperCase();
+    };
+
+    ctx.normalizeStoredUnmappedRow = function normalizeStoredUnmappedRow(node, index) {
+      if (!node || typeof node !== "object") {
+        return null;
+      }
+
+      const shortName = String(node.short_name ?? node.name ?? "").trim();
+      if (!shortName) {
+        return null;
+      }
+
+      const idCandidate = String(node.row_id ?? "").trim();
+      const rowId = idCandidate.startsWith("unmapped_") ? idCandidate : `unmapped_${index + 1}`;
+      return {
+        row_id: rowId,
+        short_name: shortName,
+        internal_name: String(node.internal_name ?? node.refName ?? node.ref_name ?? "").trim(),
+      };
+    };
+
+    ctx.buildRows = function buildRows() {
+      const rows = ctx.DEVICE_DATA.rows.map((row) => {
+        const rowId = String(row.row_id);
+        const functions = Array.isArray(row.functions) ? row.functions.slice() : [];
+        const selected = state.selectedByRowId[rowId];
+        const internalName = state.namesByRowId[rowId];
+        const selectedFunction = ctx.normalizeSelectedFunctionList(selected, functions);
+        const resolvedInternalName = typeof internalName === "string" ? internalName : "";
+
+        return {
+          row_id: row.row_id,
+          position: row.position,
+          short_name: row.short_name,
+          pin_label: row.pin_label,
+          functions,
+          selected_function: selectedFunction,
+          internal_name: resolvedInternalName,
+          needs_review: Boolean(state.reviewByRowId[rowId]),
+          is_unmapped: false,
+        };
+      });
+
+      const existingRowIds = new Set(rows.map((row) => String(row.row_id)));
+      const normalizedUnmappedRows = state.unmappedRows
+        .map((node, index) => ctx.normalizeStoredUnmappedRow(node, index))
+        .filter((node) => node !== null);
+
+      for (const [index, row] of normalizedUnmappedRows.entries()) {
+        let rowId = String(row.row_id || `unmapped_${index + 1}`);
+        if (!rowId.startsWith("unmapped_")) {
+          rowId = `unmapped_${index + 1}`;
+        }
+
+        if (existingRowIds.has(rowId)) {
+          let suffix = 1;
+          while (existingRowIds.has(`${rowId}_${suffix}`)) {
+            suffix += 1;
+          }
+          rowId = `${rowId}_${suffix}`;
+        }
+
+        existingRowIds.add(rowId);
+        const internalName = state.namesByRowId[rowId];
+        rows.push({
+          row_id: rowId,
+          position: "",
+          short_name: row.short_name,
+          pin_label: row.short_name,
+          functions: [],
+          selected_function: [],
+          internal_name: typeof internalName === "string" ? internalName : row.internal_name,
+          needs_review: Boolean(state.reviewByRowId[rowId]),
+          is_unmapped: true,
+        });
+      }
+
+      return rows;
+    };
+
+    ctx.getRowDataById = function getRowDataById(rowId) {
+      const rowKey = String(rowId);
+      if (ctx.table) {
+        const tableRow = ctx.table.getRow(rowId);
+        if (tableRow) {
+          return tableRow.getData();
+        }
+      }
+
+      return ctx.buildRows().find((row) => String(row.row_id) === rowKey) || null;
+    };
+
+    ctx.updateSelectedFunctionsForRow = function updateSelectedFunctionsForRow(rowId, value) {
+      const rowKey = String(rowId);
+      const rowData = ctx.getRowDataById(rowKey);
+      if (!rowData) {
+        return [];
+      }
+
+      const availableFunctions = Array.isArray(rowData.functions) ? rowData.functions : [];
+      const normalized = ctx.normalizeSelectedFunctionList(value, availableFunctions);
+
+      if (normalized.length > 0) {
+        state.selectedByRowId[rowKey] = normalized;
+      } else {
+        delete state.selectedByRowId[rowKey];
+      }
+
+      if (ctx.table) {
+        const tableRow = ctx.table.getRow(rowId);
+        if (tableRow) {
+          Promise.resolve(tableRow.update({ selected_function: normalized })).then(() => {
+            if (typeof tableRow.reformat === "function") {
+              tableRow.reformat();
+            }
+          });
+        }
+      }
+
+      ctx.saveStateDebounced();
+      return normalized;
+    };
+
+    ctx.applyReviewRowClass = function applyReviewRowClass(row) {
+      const data = row.getData();
+      const rowElement = row.getElement();
+      rowElement.classList.toggle("needs-review-row", Boolean(data && data.needs_review));
+    };
+  };
+}(window));