pyclickplc 0.3.2__tar.gz → 0.3.4__tar.gz

pyclickplc-0.3.4/.github/scripts/check_public_site.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Reject internal or superseded files from the public documentation site."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+BLOCKED_FILENAMES = {
+    "agents.md",
+    "claude.md",
+    "gen_llms.py",
+    "gen_reference.py",
+    "llms-full.txt",
+}
+
+
+def ascii_text(value: object) -> str:
+    return str(value).encode("ascii", errors="backslashreplace").decode("ascii")
+
+
+def blocked_reason(relative_path: Path) -> str | None:
+    parts = tuple(part.lower() for part in relative_path.parts)
+    if "internal" in parts:
+        return "path segment named internal"
+    if relative_path.name.lower() in BLOCKED_FILENAMES:
+        return f"blocked filename {relative_path.name}"
+    return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("site", type=Path, help="Generated site directory to inspect")
+    args = parser.parse_args()
+
+    site = args.site
+    if not site.is_dir():
+        print(f"ERROR: public site directory does not exist: {ascii_text(site)}")
+        return 2
+
+    violations: list[tuple[Path, str]] = []
+    for path in site.rglob("*"):
+        relative_path = path.relative_to(site)
+        if reason := blocked_reason(relative_path):
+            violations.append((relative_path, reason))
+
+    if violations:
+        for relative_path, reason in sorted(violations):
+            print(
+                "ERROR: blocked public-site path: "
+                f"{ascii_text(relative_path.as_posix())} ({reason})"
+            )
+        print(f"ERROR: public-site guard found {len(violations)} blocked path(s).")
+        return 1
+
+    print(f"OK: public-site guard passed: {ascii_text(site)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{pyclickplc-0.3.2 → pyclickplc-0.3.4}/.github/workflows/ci.yml

@@ -37,11 +37,11 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv (official Astral action)
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           # Update this as needed:
-          version: "0.9.25"
-          enable-cache: true
+          version: "0.11.29"
+          enable-cache: auto
           python-version: ${{ matrix.python-version }}
 
       - name: Set up Python (using uv)

{pyclickplc-0.3.2 → pyclickplc-0.3.4}/.github/workflows/docs.yml

@@ -3,6 +3,8 @@ name: Docs
 on:
   push:
     branches: ["main"]
+  pull_request:
+    branches: ["main"]
   workflow_dispatch:
 
 permissions:
@@ -22,10 +24,10 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
-          version: "0.9.25"
-          enable-cache: true
+          version: "0.11.29"
+          enable-cache: auto
           python-version: "3.12"
 
       - name: Set up Python
@@ -35,14 +37,26 @@ jobs:
         run: uv sync --locked --group docs
 
       - name: Build docs
-        run: uv run mkdocs build --strict
+        run: |
+          uv run --no-sync python devtools/prepare_docs.py
+          uv run --no-sync python docs/gen_reference.py --output-dir docs_build
+          uv run --no-sync python docs/gen_llms.py --docs-dir docs_build --output-file docs_build/llms.txt
+          uv run --no-sync zensical build --clean --strict
+
+      - name: Check docs routes
+        run: uv run --no-sync python devtools/check_docs_site.py docs_build site
+
+      - name: Guard public site
+        run: uv run --no-sync python .github/scripts/check_public_site.py site
 
       - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v4
         with:
           path: site
 
   deploy:
+    if: github.event_name != 'pull_request'
     needs: build
     runs-on: ubuntu-latest
     environment:

{pyclickplc-0.3.2 → pyclickplc-0.3.4}/.github/workflows/publish.yml

@@ -19,10 +19,10 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv (official Astral action)
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
-          version: "0.9.25"
-          enable-cache: true
+          version: "0.11.29"
+          enable-cache: auto
           python-version: "3.12"
 
       - name: Set up Python (using uv)

{pyclickplc-0.3.2 → pyclickplc-0.3.4}/.gitignore

@@ -153,6 +153,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/docs_build/
 
 # mypy
 .mypy_cache/

pyclickplc-0.3.2/CLAUDE.md → pyclickplc-0.3.4/AGENTS.md

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# pyclickplc Agent Guidance
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to coding agents working in this repository.
 
 ## Project Overview
 

{pyclickplc-0.3.2 → pyclickplc-0.3.4}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.4 - 2026-09-02
+
+### Added
+
+- Maintained AutomationDirect guidance for 344 documented SC/SD system nicknames, including conservative canonicalization helpers and source metadata for downstream repair workflows.
+
+## 0.3.3 - 2026-08-25
+
+### Added
+
+- `compose_structured_block_name()` for building structured block name strings from components (inverse of `parse_structured_block_name()`).
+- `parse_structured_block_name()` now recognizes `Base.Field:udt` (with explicit `:udt` suffix) and `Base:block` (without start override) in addition to existing patterns.
+
+## 0.3.2 - 2026-04-15
+
+### Changed
+
+- Pinned pymodbus to the compatible 3.12 release series and updated client/server integration for its current API.
+
 ## 0.3.1 - 2026-03-29
 
 ### Fixed

pyclickplc-0.3.4/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

pyclickplc-0.3.4/Makefile

@@ -0,0 +1,83 @@
+# Makefile for easy development workflows.
+# See development.md for docs.
+# Note GitHub Actions call uv directly, not this Makefile.
+
+.DEFAULT_GOAL := default
+
+.PHONY: default install lint test upgrade build clean docs-clean docs-generated-clean docs-generate docs-serve docs-build docs-check
+
+default: install lint test
+
+install:
+	uv sync --locked --all-extras --dev
+
+lint:
+	uv run devtools/lint.py
+
+test:
+	uv run pytest
+
+upgrade:
+	uv lock --upgrade
+	uv sync --locked --all-extras --dev
+
+build:
+	uv build
+
+# Improved Windows detection
+ifeq ($(OS),Windows_NT)
+    WINDOWS := 1
+else
+    ifeq ($(shell uname -s),Windows)
+        WINDOWS := 1
+    else
+        WINDOWS := 0
+    endif
+endif
+
+ifeq ($(WINDOWS),1)
+	# Windows commands
+	RM = powershell -Command "Remove-Item -Recurse -Force"
+	RM_SITE = powershell -Command "if (Test-Path 'site') { Remove-Item -Recurse -Force 'site' }"
+	FIND_PYCACHE = powershell -Command "Get-ChildItem -Path . -Filter '__pycache__' -Recurse -Directory | Remove-Item -Recurse -Force"
+	RM_GENERATED_DOCS = powershell -Command "if (Test-Path 'docs_build') { Remove-Item -Recurse -Force 'docs_build' }"
+else
+    # Unix commands
+    RM = rm -rf
+    RM_SITE = rm -rf site/
+    FIND_PYCACHE = find . -type d -name "__pycache__" -exec rm -rf {} +
+    RM_GENERATED_DOCS = rm -rf docs_build/
+endif
+
+docs-generate:
+	uv run --group docs python devtools/prepare_docs.py
+	uv run --group docs python docs/gen_reference.py --output-dir docs_build
+	uv run --group docs python docs/gen_llms.py --docs-dir docs_build --output-file docs_build/llms.txt
+
+docs-serve: docs-generate
+	uv run --group docs zensical serve
+
+docs-clean:
+	$(RM_SITE)
+	$(RM_GENERATED_DOCS)
+
+docs-generated-clean:
+	$(RM_GENERATED_DOCS)
+
+docs-build: docs-clean
+	uv run --group docs python devtools/prepare_docs.py
+	uv run --group docs python docs/gen_reference.py --output-dir docs_build
+	uv run --group docs python docs/gen_llms.py --docs-dir docs_build --output-file docs_build/llms.txt
+	uv run --group docs zensical build --clean --strict
+
+docs-check: docs-build
+	uv run --group docs python devtools/check_docs_site.py docs_build site
+	uv run --group docs python .github/scripts/check_public_site.py site
+
+clean:
+	$(RM) dist/
+	$(RM) *.egg-info/
+	$(RM) .pytest_cache/
+	$(RM) .mypy_cache/
+	$(RM) .venv/
+	$(FIND_PYCACHE)

{pyclickplc-0.3.2 → pyclickplc-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyclickplc
-Version: 0.3.2
+Version: 0.3.4
 Summary: Utilities for AutomationDirect CLICK PLCs: Modbus TCP client/server, address helpers, nickname CSV I/O, and DataView CDV I/O.
 Project-URL: Repository, https://github.com/ssweber/pyclickplc
 Project-URL: Documentation, https://ssweber.github.io/pyclickplc/

pyclickplc-0.3.4/devtools/check_docs_site.py

@@ -0,0 +1,140 @@
+"""Validate generated documentation inputs and their published routes."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path, PurePosixPath
+from urllib.parse import unquote, urlparse
+
+EXPECTED_REFERENCE_SOURCES = {
+    PurePosixPath("reference/index.md"),
+    PurePosixPath("reference/api/client.md"),
+    PurePosixPath("reference/api/service.md"),
+    PurePosixPath("reference/api/server.md"),
+    PurePosixPath("reference/api/files.md"),
+    PurePosixPath("reference/api/addressing.md"),
+    PurePosixPath("reference/api/validation.md"),
+    PurePosixPath("reference/api/advanced.md"),
+}
+EXPECTED_AUTHORED_SOURCES = {
+    PurePosixPath("index.md"),
+    PurePosixPath("getting-started/quickstart.md"),
+    PurePosixPath("guides/client.md"),
+    PurePosixPath("guides/types.md"),
+    PurePosixPath("guides/addressing.md"),
+    PurePosixPath("guides/modbus_service.md"),
+    PurePosixPath("guides/server.md"),
+    PurePosixPath("guides/files.md"),
+    PurePosixPath("guides/examples.md"),
+    PurePosixPath("releases/v0.2.0.md"),
+    PurePosixPath("releases/v0.3.0.md"),
+}
+EXPECTED_SITEMAP_SOURCES = (EXPECTED_AUTHORED_SOURCES | EXPECTED_REFERENCE_SOURCES) - {
+    PurePosixPath("releases/v0.3.0.md")
+}
+MARKDOWN_LINK = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
+
+
+def ascii_text(value: object) -> str:
+    return str(value).encode("ascii", errors="backslashreplace").decode("ascii")
+
+
+def _route_for_source(source: PurePosixPath) -> PurePosixPath:
+    if source.name == "index.md":
+        return source.with_name("index.html")
+    return source.with_suffix("") / "index.html"
+
+
+def _route_for_url(url: str, site_prefix: str) -> PurePosixPath | None:
+    parsed = urlparse(url)
+    path = unquote(parsed.path)
+    if not path.startswith(site_prefix):
+        return None
+    relative = path[len(site_prefix) :].lstrip("/")
+    if not relative or path.endswith("/"):
+        return PurePosixPath(relative) / "index.html"
+    candidate = PurePosixPath(relative)
+    return candidate if candidate.suffix else candidate / "index.html"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("docs", type=Path, help="Documentation source directory")
+    parser.add_argument("site", type=Path, help="Generated site directory")
+    args = parser.parse_args()
+
+    docs = args.docs.resolve()
+    site = args.site.resolve()
+    errors: list[str] = []
+
+    actual_authored = {
+        PurePosixPath(path.relative_to(docs).as_posix())
+        for path in docs.rglob("*.md")
+        if "reference" not in path.relative_to(docs).parts
+        and path.name.lower() not in {"agents.md", "claude.md"}
+    }
+    if actual_authored != EXPECTED_AUTHORED_SOURCES:
+        missing = sorted(EXPECTED_AUTHORED_SOURCES - actual_authored)
+        extra = sorted(actual_authored - EXPECTED_AUTHORED_SOURCES)
+        if missing:
+            errors.append("missing authored sources: " + ", ".join(map(str, missing)))
+        if extra:
+            errors.append("unexpected authored sources: " + ", ".join(map(str, extra)))
+
+    actual_references = {
+        PurePosixPath(path.relative_to(docs).as_posix())
+        for path in (docs / "reference").rglob("*.md")
+    }
+    if actual_references != EXPECTED_REFERENCE_SOURCES:
+        missing = sorted(EXPECTED_REFERENCE_SOURCES - actual_references)
+        extra = sorted(actual_references - EXPECTED_REFERENCE_SOURCES)
+        if missing:
+            errors.append("missing generated reference sources: " + ", ".join(map(str, missing)))
+        if extra:
+            errors.append("unexpected generated reference sources: " + ", ".join(map(str, extra)))
+
+    sitemap_file = site / "sitemap.xml"
+    sitemap = sitemap_file.read_text(encoding="utf-8") if sitemap_file.is_file() else ""
+    for source in sorted(EXPECTED_AUTHORED_SOURCES | EXPECTED_REFERENCE_SOURCES):
+        route = _route_for_source(source)
+        if not (site / Path(route.as_posix())).is_file():
+            errors.append(f"missing documentation route: {route}")
+        if source in EXPECTED_SITEMAP_SOURCES:
+            public_route = "/pyclickplc/" + route.parent.as_posix().strip(".") + "/"
+            if public_route.replace("//", "/") not in sitemap:
+                errors.append(f"documentation route missing from sitemap: {public_route}")
+
+    source_llms = docs / "llms.txt"
+    built_llms = site / "llms.txt"
+    if not source_llms.is_file():
+        errors.append("missing generated docs/llms.txt")
+    elif not built_llms.is_file():
+        errors.append("missing published site/llms.txt")
+    elif source_llms.read_bytes() != built_llms.read_bytes():
+        errors.append("published llms.txt does not match the generated source")
+    else:
+        llms_text = built_llms.read_text(encoding="utf-8")
+        for url in MARKDOWN_LINK.findall(llms_text):
+            if urlparse(url).path.endswith(".md"):
+                errors.append(f"llms.txt uses a Markdown route: {url}")
+            route = _route_for_url(url, "/pyclickplc/")
+            if route is not None and not (site / Path(route.as_posix())).is_file():
+                errors.append(f"llms.txt target is not published: {url}")
+
+    for llms_full in (docs / "llms-full.txt", site / "llms-full.txt"):
+        if llms_full.exists():
+            errors.append(f"llms-full.txt must not be generated: {llms_full}")
+
+    if errors:
+        for error in errors:
+            print(f"ERROR: {ascii_text(error)}")
+        print(f"ERROR: docs-site check found {len(errors)} problem(s).")
+        return 1
+
+    print("OK: authored/generated docs inputs, routes, and llms.txt match.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyclickplc-0.3.4/devtools/prepare_docs.py

@@ -0,0 +1,80 @@
+"""Prepare publishable authored documentation in an ignored build directory."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+SOURCE_DOCS_DIR = ROOT_DIR / "docs"
+OUTPUT_DOCS_DIR = ROOT_DIR / "docs_build"
+BLOCKED_FILENAMES = {
+    "agents.md",
+    "claude.md",
+    "gen_llms.py",
+    "gen_reference.py",
+    "llms-full.txt",
+    "llms.txt",
+}
+
+
+def _is_publishable(relative_path: Path) -> bool:
+    parts = tuple(part.lower() for part in relative_path.parts)
+    if "internal" in parts or "__pycache__" in parts:
+        return False
+    if parts and parts[0] == "reference":
+        return False
+    if relative_path.suffix.lower() in {".py", ".pyc", ".pyo"}:
+        return False
+    return relative_path.name.lower() not in BLOCKED_FILENAMES
+
+
+def prepare(
+    source_dir: Path = SOURCE_DOCS_DIR,
+    output_dir: Path = OUTPUT_DOCS_DIR,
+) -> tuple[Path, ...]:
+    """Copy publishable source files into a clean generated docs directory."""
+    source_dir = source_dir.resolve()
+    output_dir = output_dir.resolve()
+    if output_dir == source_dir or output_dir.is_relative_to(source_dir):
+        raise RuntimeError("Prepared docs directory must be outside source docs.")
+
+    if output_dir.exists():
+        shutil.rmtree(output_dir)
+    output_dir.mkdir(parents=True)
+
+    copied: list[Path] = []
+    for source in sorted(path for path in source_dir.rglob("*") if path.is_file()):
+        relative_path = source.relative_to(source_dir)
+        if not _is_publishable(relative_path):
+            continue
+        destination = output_dir / relative_path
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)
+        copied.append(destination)
+    return tuple(copied)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--source-dir",
+        type=Path,
+        default=SOURCE_DOCS_DIR,
+        help="Authored documentation directory",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=OUTPUT_DOCS_DIR,
+        help="Ignored directory to receive publishable documentation",
+    )
+    args = parser.parse_args()
+    copied = prepare(args.source_dir, args.output_dir)
+    print(f"Prepared {len(copied)} authored documentation file(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyclickplc-0.3.2/docs/CLAUDE.md → pyclickplc-0.3.4/docs/AGENTS.md

@@ -1,4 +1,4 @@
-# pyclickplc Documentation — Context for Claude
+# pyclickplc Documentation — Agent Context
 
 ## What is pyclickplc
 

pyclickplc-0.3.4/docs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

pyclickplc-0.3.4/docs/gen_llms.py

@@ -0,0 +1,117 @@
+"""Generate the curated llms.txt index for the pyclickplc documentation site."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path, PurePosixPath
+from urllib.parse import urljoin
+
+DOCS_DIR = Path(__file__).resolve().parent
+CONFIG_FILE = DOCS_DIR.parent / "mkdocs.yml"
+
+SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
+    ("Getting Started", (("Quickstart", "getting-started/quickstart.md"),)),
+    (
+        "Guides",
+        (
+            ("Addressing", "guides/addressing.md"),
+            ("Client", "guides/client.md"),
+            ("Examples", "guides/examples.md"),
+            ("File I/O", "guides/files.md"),
+            ("Modbus Service", "guides/modbus_service.md"),
+            ("Server & Simulator", "guides/server.md"),
+            ("Types & Values", "guides/types.md"),
+        ),
+    ),
+    (
+        "API Reference",
+        (
+            ("Overview", "reference/index.md"),
+            ("Addressing API", "reference/api/addressing.md"),
+            ("Advanced API", "reference/api/advanced.md"),
+            ("Client API", "reference/api/client.md"),
+            ("Files API", "reference/api/files.md"),
+            ("Server API", "reference/api/server.md"),
+            ("Service API", "reference/api/service.md"),
+            ("Validation API", "reference/api/validation.md"),
+        ),
+    ),
+)
+
+
+def _simple_config_value(config_file: Path, key: str) -> str:
+    pattern = re.compile(rf"^{re.escape(key)}:\s*(.*?)\s*$")
+    for line in config_file.read_text(encoding="utf-8").splitlines():
+        if match := pattern.match(line):
+            return match.group(1).strip("\"'")
+    raise RuntimeError(f"Missing {key!r} in {config_file}.")
+
+
+def _page_url(site_url: str, source_path: str) -> str:
+    path = PurePosixPath(source_path)
+    if path.name == "index.md":
+        route = path.parent.as_posix()
+    else:
+        route = path.with_suffix("").as_posix()
+    return urljoin(site_url.rstrip("/") + "/", route.rstrip("/") + "/")
+
+
+def generate(
+    output_file: Path = DOCS_DIR / "llms.txt",
+    *,
+    docs_dir: Path = DOCS_DIR,
+    config_file: Path = CONFIG_FILE,
+) -> Path:
+    """Generate the curated HTML-route index used by public agents."""
+    site_name = _simple_config_value(config_file, "site_name")
+    site_description = _simple_config_value(config_file, "site_description")
+    site_url = _simple_config_value(config_file, "site_url")
+    lines = [f"# {site_name}", "", f"> {site_description}", ""]
+
+    for section, pages in SECTIONS:
+        lines.extend((f"## {section}", ""))
+        for label, source_path in pages:
+            markdown_file = docs_dir / Path(source_path)
+            if not markdown_file.is_file():
+                raise RuntimeError(f"Missing llms.txt source page: {markdown_file}.")
+            lines.append(f"- [{label}]({_page_url(site_url, source_path)})")
+        lines.append("")
+
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    output_file.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+    return output_file
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--docs-dir",
+        type=Path,
+        default=DOCS_DIR,
+        help="Prepared documentation source directory",
+    )
+    parser.add_argument(
+        "--config-file",
+        type=Path,
+        default=CONFIG_FILE,
+        help="Site configuration containing name, description, and URL",
+    )
+    parser.add_argument(
+        "--output-file",
+        type=Path,
+        default=DOCS_DIR / "llms.txt",
+        help="Path to generated llms.txt",
+    )
+    args = parser.parse_args()
+    generate(
+        args.output_file.resolve(),
+        docs_dir=args.docs_dir.resolve(),
+        config_file=args.config_file.resolve(),
+    )
+    print("Generated llms.txt.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())