From 245f5f384950bf08177957bca0017f49136ebf65 Mon Sep 17 00:00:00 2001 From: Karl Kauc Date: Fri, 15 May 2026 22:19:07 +0200 Subject: [PATCH] docs: close documentation gaps in example source files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audited all example source files against the repo's teaching-doc standard (file-header purpose/run/deps/assumptions + what/why + security note). Six fell short; fixed with comment-only changes (no behaviour change): - Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl: add the missing file header (purpose, run command, why XSLT 1.0, deps, FundsXML no-namespace + UniqueID-key rationale + tolerance sync note) — it was the only example with no header at all. - XSLT_Transformations/invocation/RunTransform.java, XQuery_Examples/invocation/RunXQuery.java: add explicit Dependencies line and note they are generic FundsXML-agnostic invocation wrappers. - Large_File_Processing/python/{stream_aggregate,split,delta_diff}.py: add explicit Dependencies + Security lines (the iterparse calls were already XXE-hardened; now documented). The other ~35 example files were audited and already meet the standard. Verified: Enhanced report still renders; the Python files compile & run. Co-Authored-By: Claude Opus 4.7 (1M context) --- Large_File_Processing/python/delta_diff.py | 6 +++++ Large_File_Processing/python/split.py | 4 ++++ .../python/stream_aggregate.py | 4 ++++ XQuery_Examples/invocation/RunXQuery.java | 8 +++++++ .../FundsXML_CompleteDQReport_HTML.xsl | 24 +++++++++++++++++++ .../invocation/RunTransform.java | 10 ++++++-- 6 files changed, 54 insertions(+), 2 deletions(-) diff --git a/Large_File_Processing/python/delta_diff.py b/Large_File_Processing/python/delta_diff.py index e787fa0..928f3c3 100644 --- a/Large_File_Processing/python/delta_diff.py +++ b/Large_File_Processing/python/delta_diff.py @@ -13,6 +13,12 @@ Both files are streamed with iterparse (constant memory). Exit code: 0 if the sets are identical, 1 if there are differences, 2 on usage error. + +FundsXML 4.x has no XML namespace — bare element names. +Dependencies: lxml (`pip install lxml`); Python stdlib otherwise. +Security: iterparse runs with resolve_entities=False, no_network=True +(XXE / external-entity safe on untrusted feeds). The 0.005 tolerance absorbs +2-dp rounding so re-exported numbers don't show as spurious "changed". """ import json import sys diff --git a/Large_File_Processing/python/split.py b/Large_File_Processing/python/split.py index 9f485ff..4223377 100644 --- a/Large_File_Processing/python/split.py +++ b/Large_File_Processing/python/split.py @@ -10,6 +10,10 @@ Useful for parallel downstream processing or staying under message-size limits. FundsXML 4.x has no XML namespace. + +Dependencies: lxml (`pip install lxml`); Python stdlib otherwise. +Security: iterparse runs with resolve_entities=False, no_network=True +(XXE / external-entity safe on untrusted feeds). """ import sys from pathlib import Path diff --git a/Large_File_Processing/python/stream_aggregate.py b/Large_File_Processing/python/stream_aggregate.py index 1325055..150baf6 100644 --- a/Large_File_Processing/python/stream_aggregate.py +++ b/Large_File_Processing/python/stream_aggregate.py @@ -9,6 +9,10 @@ (the classic lxml fast_iter pattern). Prints the totals and peak RSS. FundsXML 4.x has no XML namespace — match the bare 'Position' tag. + +Dependencies: lxml (`pip install lxml`); Python stdlib otherwise. +Security: iterparse runs with resolve_entities=False, no_network=True and +huge_tree=False — XXE / entity-expansion safe even on untrusted feeds. """ import resource import sys diff --git a/XQuery_Examples/invocation/RunXQuery.java b/XQuery_Examples/invocation/RunXQuery.java index 63e549d..3cf41e2 100644 --- a/XQuery_Examples/invocation/RunXQuery.java +++ b/XQuery_Examples/invocation/RunXQuery.java @@ -6,6 +6,14 @@ // java -cp "$SCP:/tmp/xq" RunXQuery [k=v ...] // Exit: 0 success, 2 setup error. // +// Dependencies: Saxon-HE + xmlresolver jars only (fetched by +// tools/fetch-tools.sh into .lib/); no other libraries. +// +// This is a generic, FundsXML-agnostic XQuery runner: it binds the input as +// the context item and passes string external variables — the FundsXML +// specifics (no XML namespace, Position↔Asset by UniqueID) live in the .xq +// files it runs. s9api is Saxon's idiomatic Java API; no JAXB. +// // External query variables are passed as k=v args (string-typed), e.g. n=5. import java.io.File; diff --git a/XSLT_DataQuality_Checks/Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl b/XSLT_DataQuality_Checks/Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl index 2b3b4c0..75f80ce 100644 --- a/XSLT_DataQuality_Checks/Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl +++ b/XSLT_DataQuality_Checks/Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl @@ -1,4 +1,28 @@ + diff --git a/XSLT_Transformations/invocation/RunTransform.java b/XSLT_Transformations/invocation/RunTransform.java index 49e82ce..212c71b 100644 --- a/XSLT_Transformations/invocation/RunTransform.java +++ b/XSLT_Transformations/invocation/RunTransform.java @@ -6,8 +6,14 @@ // java -cp "$SCP:/tmp/rt" RunTransform [k=v ...] // Exit: 0 success, 2 setup error. // -// The repo's stylesheets are XSLT 2.0; Saxon supplies the engine. s9api is -// Saxon's idiomatic Java API — no JAXB involved. +// Dependencies: Saxon-HE + xmlresolver jars only (fetched by +// tools/fetch-tools.sh into .lib/); no other libraries. +// +// This is a generic, FundsXML-agnostic invocation wrapper: it applies any +// stylesheet to any XML and passes through string parameters (k=v) — the +// FundsXML specifics live in the .xslt files it runs. The repo's stylesheets +// are XSLT 2.0; Saxon supplies the engine. s9api is Saxon's idiomatic Java +// API — no JAXB involved (a full data binding would be needless here). import java.io.File; import net.sf.saxon.s9api.Processor;