From 053f40e9b42ee5d0b0bd4d146b9866ba5a372173 Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Sun, 12 Jul 2026 12:14:44 +0100 Subject: [PATCH] Clarify handling of script metadata --- source/specifications/inline-script-metadata.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/source/specifications/inline-script-metadata.rst b/source/specifications/inline-script-metadata.rst index 6fa832a3e..0f0285307 100644 --- a/source/specifications/inline-script-metadata.rst +++ b/source/specifications/inline-script-metadata.rst @@ -70,6 +70,17 @@ and the regular expression, the text specification takes precedence. Tools MUST NOT read from metadata blocks with types that have not been standardized by this specification. +Note that the specification only requires that *top-level* comment blocks are +recognised as containing metadata. However, parsing Python code is non-trivial, +and therefore: + +* Tools MAY choose to do a simple textual scan, rather than a full Python parse. + For example, the canonical regular expression provided above does a textual + scan. +* As a result of the previous point, the behaviour of scripts that contain data + that looks like metadata within another Python construct such as a multi-line + string is tool-dependent and should not be relied on. + script type -----------