Python: Normalize sample structure and public imports #9630

Maintainer-owned issue. Community contributors: please do not pick up or start implementing this issue.

Category

Documentation

Problem

Python samples do not consistently follow the new copyright, PEP 723 metadata, module-docstring, and stable-public-import standards.

Evidence

The audit found approximately 94 test/sample files without copyright on the first line; about 74 are PEP 723 samples with metadata before the copyright. Approximately 15 samples lack module docstrings. Some samples import private implementation modules rather than supported public surfaces.

Desired Outcome

Apply the documented sample ordering, add concise module docstrings to executable user-facing samples, and replace private imports with existing supported public imports. Do not make private helpers public solely to simplify a sample.

Language

Python

Acknowledgements

• I searched existing issues and did not find a duplicate.
• I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

Static Enforcement

Ruff CPY001 already checks that a copyright notice appears within the first 4096 bytes, but it does not enforce first-line placement or the copyright -> optional PEP 723 metadata -> module-docstring ordering. Add a focused repository check for that ordering and include it in the existing sample/code-quality validation path.

Ownership: Core maintainers only; not available for community pickup.