Use semantically safe inline frontmatter for Python files

[DandyLyons]

Summary

Reassess Python's shipped inline-frontmatter representation now that per-line hash-comment frontmatter is available. The current triple-quoted representation can change Python module semantics when frontmatter is created in an existing file.

Python-specific concerns

Module docstrings

The first string-literal statement becomes the module docstring and is exposed as module.doc. Creating triple-quoted YAML before an existing module docstring causes the metadata string to become module.doc and demotes the intended documentation to an unused string expression.

Future imports

Python permits future imports after the module docstring and comments. Inserting a metadata string before an existing module docstring creates a second string expression before the future import, which can make an otherwise valid file fail with a future-import placement SyntaxError.

Representative input:

"""Actual module documentation."""

from __future__ import annotations

Encoding declarations and shebangs

Python encoding declarations are recognized only in the legal leading-line positions, and executable scripts may also begin with a shebang. Frontmatter creation must preserve those semantics and positions.

Stub and tooling behavior

Python and Pyi files may be inspected by documentation generators, type checkers, and other tools that assign meaning to module docstrings. Frontmatter should not unintentionally replace that documentation surface.

Proposed direction

Prefer per-line hash-comment frontmatter for newly created Python and Pyi metadata:

# ---
# title: Example
# description: Demonstrates inline metadata.
# ---

"""Actual module documentation."""

Changing the shipped mapping outright would strand existing python-docstring frontmatter, so design a backward-compatible migration:

• Continue recognizing and mutating existing triple-quoted frontmatter.
• Create new Python frontmatter using the hash-comment representation.
• Define deterministic behavior if both representations are present.
• Preserve shebangs, encoding declarations, line endings, and surrounding source.
• Keep representation selection and rewriting inside md-utils so consumers only get and set decoded metadata.

Acceptance criteria

• Newly created Python and Pyi frontmatter does not replace or alter module.doc.
• A valid module docstring followed by a future import remains valid after frontmatter creation.
• Shebang and encoding-declaration fixtures retain their Python semantics.
• Existing python-docstring frontmatter remains readable and safely mutable, or a documented migration path is provided.
• Files containing both representations receive deterministic multiplicity or precedence handling.
• Representative files pass Python syntax compilation before and after mutation.
• Documentation explains the selected Python representation and compatibility behavior.

Related work

• Add delimiter-wrapped frontmatter support for non-Markdown files #98
• Add per-line hash-comment frontmatter #129