connections-export 0.1.0__tar.gz

connections_export-0.1.0/.github/workflows/binaries.yml

@@ -0,0 +1,144 @@
+name: Binaries
+
+# Single-file executables for people who will not install Python, attached to
+# the GitHub Release on `v*`.
+#
+# When they are built depends on what it costs. Four platform builds -- two of
+# them macOS -- is the most expensive thing here, and on a private repository
+# macOS bills at 10x, so there they run on a tag or on request only. On a
+# public repository standard runners are free, so they run on every push to
+# main as well: a packaging fault found on a push is found before a tag exists,
+# and a tag is a bad place to discover one.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    # Free on a public repo, so every push; metered on a private one, so tags
+    # and explicit requests only.
+    if: >-
+      github.event.repository.private == false
+      || startsWith(github.ref, 'refs/tags/v')
+      || github.event_name == 'workflow_dispatch'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x86_64
+          - os: macos-latest
+            target: macos-arm64
+          # Intel macOS. NOT `macos-13` -- GitHub retired those runners, and a
+          # retired label does not fail, it queues forever: the first two runs
+          # here sat unassigned for over an hour while the other three
+          # platforms had long since finished, and the run never reported.
+          - os: macos-15-intel
+            target: macos-x86_64
+          - os: windows-latest
+            target: windows-x86_64
+    runs-on: ${{ matrix.os }}
+    # A PyInstaller build is minutes, not tens of minutes. The cap turns a hung
+    # or unservable cell into a failure someone can see.
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          # PyInstaller embeds the interpreter it builds against, so the
+          # executable IS this Python version. Pinned rather than matrixed:
+          # one binary per platform, not one per Python.
+          python-version: "3.13"
+          enable-cache: true
+
+      # `requests-kerberos` pulls `krb5`, which builds against system Kerberos
+      # headers that the Linux runners do not ship -- `--all-extras` therefore
+      # fails at resolve time on Linux alone. Same wall a Linux user installing
+      # `connections-export[sspi]` hits, so the fix belongs in the docs too.
+      - name: Kerberos headers (Linux only, for the sspi extra)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq libkrb5-dev
+
+      # `--all-extras` is what puts markdownify in the environment, and so in
+      # the bundle: the Obsidian ingester imports it lazily, which means a
+      # bundle built without it still starts and still passes `--help`.
+      # build_binary.py asserts the module is present rather than trusting it.
+      - name: Build executable
+        run: uv run --all-extras --python 3.13 python tools/build_binary.py --dist dist
+
+      # The point of the executable is that a user with no Python and no
+      # install can run it, so the smoke test uses the binary ALONE -- no uv,
+      # no source, no helper script. `--demo` renders the synthetic deployment
+      # that ships inside it; PDF rendering is the one thing that reaches
+      # outside, for a Chromium-based browser. On Windows that is the
+      # preinstalled Edge, which is the path most users will take.
+      - name: Smoke-test the executable, standalone
+        shell: bash
+        run: |
+          set -euo pipefail
+          exe="dist/connections-export"
+          [ "${{ runner.os }}" = "Windows" ] && exe="dist/connections-export.exe"
+          "$exe" --help > /dev/null
+          "$exe" crawl --demo --output-dir demo-archive
+          "$exe" pdf --demo --output smoke.pdf
+          # A PDF header and a plausible size: the demo set renders ~100 pages,
+          # so anything tiny means it rendered nothing and still exited 0.
+          head -c 5 smoke.pdf | grep -q '%PDF' || { echo "not a PDF"; exit 1; }
+          size=$(wc -c < smoke.pdf)
+          echo "smoke.pdf: $size bytes on ${{ matrix.target }}"
+          [ "$size" -gt 100000 ] || { echo "PDF suspiciously small"; exit 1; }
+          rm -rf demo-archive smoke.pdf
+
+      - name: Name the artifact after the version and platform
+        shell: bash
+        run: |
+          # `uv run --no-project`, not bare `python`: setup-uv provisions a
+          # managed interpreter without guaranteeing `python` on PATH, and
+          # --no-project skips a pointless re-sync just to read a TOML key.
+          version="$(uv run --no-project python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          src="dist/connections-export"; ext=""
+          if [ "${{ runner.os }}" = "Windows" ]; then src="dist/connections-export.exe"; ext=".exe"; fi
+          mv "$src" "dist/connections-export-${version}-${{ matrix.target }}${ext}"
+          ls -la dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: connections-export-${{ matrix.target }}
+          path: dist/connections-export-*
+          if-no-files-found: error
+          # Four executables are ~290 MB a run, and GitHub keeps artifacts for
+          # 90 days by default. On a PRIVATE repo that is metered storage: seven
+          # runs had accumulated 2 GB against a 500 MB allowance. These are
+          # disposable -- rebuildable from any tag -- and on a `v*` tag the
+          # release assets are the copy that lasts.
+          retention-days: 7
+
+  attach-to-release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist/
+          merge-multiple: true
+      # `gh release upload` fails if no Release object exists, and release.yml
+      # only publishes to PyPI -- pushing a tag does not create one. Create it
+      # if absent, then upload; `--clobber` makes a re-run idempotent.
+      - name: Attach executables to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1 \
+            || gh release create "$GITHUB_REF_NAME" \
+                 --repo "$GITHUB_REPOSITORY" \
+                 --title "$GITHUB_REF_NAME" \
+                 --generate-notes
+          gh release upload "$GITHUB_REF_NAME" dist/* --clobber --repo "$GITHUB_REPOSITORY"

connections_export-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+# How much of the matrix runs depends on whether the repository is private,
+# because that is what decides whether it costs anything.
+#
+#   public  -> everything, on every push. GitHub-hosted standard runners are
+#              free for public repositories, so there is no reason to prove
+#              less than the whole matrix.
+#   private -> Linux only on a push; the full 3 OS x 3 Python matrix on a tag
+#              or on request. Minutes are metered there, and metered unevenly:
+#              macOS bills at 10x and Windows at 2x, so a nine-cell matrix on
+#              every push costs roughly 350 metered minutes and exhausts a
+#              modest allowance in a day.
+#
+# Linux alone catches most of it -- a dependency without wheels for a new
+# Python fails at resolve time on any OS -- but the claim that `requires-python`
+# is honoured can only be proved by running there.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      # `requests-kerberos` pulls `krb5`, which builds against system Kerberos
+      # headers that the Linux runners do not ship -- `--all-extras` therefore
+      # fails at resolve time on Linux alone. Same wall a Linux user installing
+      # `connections-export[sspi]` hits, so the fix belongs in the docs too.
+      - name: Kerberos headers (Linux only, for the sspi extra)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq libkrb5-dev
+
+      # No Playwright browsers installed on purpose: the suite runs offline
+      # against the in-process fake server; the ~2 browser-PDF tests skip.
+      - name: Lint
+        run: |
+          uv run --all-extras ruff check .
+          uv run --all-extras ruff format --check .
+      - name: Tests
+        run: uv run --all-extras pytest
+
+  # The expensive half: only before a release, or when asked. macOS bills at
+  # 10x and Windows at 2x, so this job costs more than everything else in the
+  # repo combined -- which is exactly why it does not run on every push.
+  cross-platform:
+    # Free on a public repo, so always; metered on a private one, so only
+    # when it is worth paying for.
+    if: >-
+      github.event.repository.private == false
+      || startsWith(github.ref, 'refs/tags/v')
+      || github.event_name == 'workflow_dispatch'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+        python: ["3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - name: Lint
+        run: |
+          uv run --all-extras ruff check .
+          uv run --all-extras ruff format --check .
+      - name: Tests
+        run: uv run --all-extras pytest

connections_export-0.1.0/.github/workflows/packages.yml

@@ -0,0 +1,181 @@
+name: Packages
+
+# Wheel + sdist on every push to main, so staging proves the distributions the
+# same way it proves the executables -- and `twine check` renders the README the
+# way PyPI will, which is the one packaging fault a local install cannot show.
+#
+# The TestPyPI upload below is deliberately DORMANT: it never runs on a push,
+# only when someone dispatches it by hand with publish=true. Before it can work,
+# two things must exist (neither is created by this file):
+#   * a TestPyPI Trusted Publisher for this owner/repo naming `packages.yml`
+#     and the `testpypi` environment
+#   * a repository Environment named `testpypi`
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Upload the built distributions to TestPyPI"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Build wheel and sdist
+        run: uv build --out-dir dist
+
+      # A package index renders the README as the project description. A
+      # malformed one is rejected at upload, or silently renders wrong, and a
+      # relative link that resolves in a checkout may not resolve there.
+      - name: Validate metadata and description rendering
+        run: uvx twine check --strict dist/*
+
+      - name: Report what was built
+        run: ls -l dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          # Small (~2 MB) but uploaded on every push; no reason to keep 90 days
+          # of them on metered storage.
+          retention-days: 7
+
+  # What only a real install can show. The tests run against the source tree,
+  # where the working copy has answered every question the same way for so long
+  # that some of them stopped being asked: bytecode is cached, the repository is
+  # on `sys.path`, and a data file is found because `docs/` happens to be next
+  # door. A fresh venv with nothing but the wheel in it has none of that.
+  #
+  # Runs on every push, before the dormant upload below, so a fault of this kind
+  # is found while the version number is still free to reuse.
+  smoke:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Install the built wheel into an empty environment
+        run: |
+          uv venv /tmp/smoke
+          VIRTUAL_ENV=/tmp/smoke uv pip install dist/*.whl
+
+      # Deliberately not from the repository root: Python puts the working
+      # directory on `sys.path`, so a check run there imports the checkout and
+      # the wheel is never touched.
+      - name: It runs, and says nothing it was not asked to say
+        working-directory: /tmp
+        run: |
+          set -euo pipefail
+          /tmp/smoke/bin/connections-export --help >/tmp/out.txt 2>/tmp/err.txt
+          echo "--- stdout ---"; cat /tmp/out.txt
+          if [ -s /tmp/err.txt ]; then
+            echo "::error::the console script wrote to stderr; a user sees this"
+            cat /tmp/err.txt
+            exit 1
+          fi
+          if grep -qi stub /tmp/out.txt; then
+            echo "::error::a stub command is advertised in the public help"
+            exit 1
+          fi
+
+      # A SyntaxWarning is raised once, when the `.pyc` is written -- long ago
+      # in a working tree, and on a new install either during it or on stderr of
+      # every command until a cache warms. Compiling on purpose catches both.
+      - name: Every installed module compiles without warnings
+        working-directory: /tmp
+        run: |
+          SITE=$(/tmp/smoke/bin/python -P -c \
+            "import connections_export,pathlib;print(pathlib.Path(connections_export.__file__).parent)")
+          /tmp/smoke/bin/python -W error::SyntaxWarning -m compileall -q -f -x vendor "$SITE"
+
+      # The documents the application READS, not merely ships beside: the
+      # manual is the console's Manual tab, and the spec is copied into every
+      # package written.
+      - name: Its own documents are inside it, and readable
+        working-directory: /tmp
+        run: |
+          /tmp/smoke/bin/python -P - <<'PY'
+          import pathlib
+          import connections_export
+          from connections_export.gui.manual import MANUAL_DOC_PATH, manual_html
+          from connections_export.interchange.package import SPEC_DOC_PATH
+
+          root = pathlib.Path(connections_export.__file__).parent
+          assert MANUAL_DOC_PATH.is_file(), f"no manual at {MANUAL_DOC_PATH}"
+          assert SPEC_DOC_PATH.is_file(), f"no interchange spec at {SPEC_DOC_PATH}"
+          assert (root / "architecture.md").is_file(), "no architecture document"
+          html = manual_html()
+          assert html.count("<h2") >= 10, f"the manual rendered {html.count('<h2')} sections"
+          print(f"manual renders: {len(html)} chars, {html.count('<h2')} sections")
+          PY
+
+      # The console serves its own page, with the manual already in it -- and
+      # refuses a caller that is not local. The console reads archives and can
+      # start a capture with the user's own credentials, so it answers to this
+      # machine and nothing else; that guard is worth proving in the artefact
+      # that ships rather than only in the tests.
+      - name: The console starts, serves a complete page, and stays local
+        working-directory: /tmp
+        run: |
+          /tmp/smoke/bin/python -P - <<'PY'
+          import asyncio
+          import httpx
+          from connections_export.gui.app import make_app
+
+          async def get(base):
+              transport = httpx.ASGITransport(app=make_app(demo=True))
+              async with httpx.AsyncClient(transport=transport, base_url=base) as c:
+                  return await c.get("/")
+
+          r = asyncio.run(get("http://127.0.0.1"))
+          assert r.status_code == 200, r.status_code
+          assert 'id="man-intro"' in r.text, "the manual is not in the served page"
+          assert "<!--MANUAL-->" not in r.text, "the manual placeholder was never filled"
+          print(f"console serves {len(r.text)} chars with the manual in place")
+
+          elsewhere = asyncio.run(get("http://elsewhere.example"))
+          assert elsewhere.status_code == 403, (
+              f"a non-local caller got {elsewhere.status_code}, not 403"
+          )
+          print("a non-local caller is refused")
+          PY
+
+  publish-testpypi:
+    # Dormant until dispatched by hand. Nothing on a push can reach this job.
+    if: github.event_name == 'workflow_dispatch' && inputs.publish
+    needs: [build, smoke]
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/connections-export
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

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

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Confirm tag matches package version
+        run: |
+          version="$(uv run --no-project python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "v${version}" = "$GITHUB_REF_NAME"
+      - name: Build distributions
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

connections_export-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Node
+node_modules/
+*.log
+
+# Crawl output holds exported content and session tokens -- never commit.
+# Anchored to the repository root so it does not match the
+# connections_export/archive source package or tests/archive.
+/archive/
+*.ltpa
+.env
+.env.*
+
+# Your own config: copy connections-export.example.toml and fill it in. It
+# names your deployment, so it is never committed.
+connections-export.toml
+
+# hcl-serve's default run-archive location when run from the repo root
+# (CONNECTIONS_EXPORT_ARCHIVES_DIR unset) — dev/testing archives, never commit.
+/connections-export-archives/

connections_export-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Jörg Türmer
+
+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.