Functions
tuple[ast.Module\|None, list[str]]	safe_parse (str text)
int	header_boundary (list[str] lines, Path path, str\|None expected_identity=None)

Variables
	_ENCODING_RE = re.compile(r"#.*coding[:=]")

Detailed Description

Purpose
-------
Provide shared Python-source parsing helpers:

- :func:`safe_parse` parses source text into an AST while capturing any
  ``SyntaxWarning`` diagnostics (so callers can surface them without
  letting them leak to stderr).
- :func:`header_boundary` (OI-509 / FS-505) returns the line index where
  file content begins, scanning at most the first 5 lines in the strict
  order shebang → encoding → file-identity comment → blank line. This
  replaces two drift-prone inline copies that previously existed in the
  linter and the formatter.

Responsibilities
----------------
- Parse Python source text into an AST tree.
- Capture ``SyntaxWarning`` (e.g. invalid escape sequences) as structured data.
- Locate the header/content boundary of an Option-C-formatted Python file
  using only the file's basename and (optionally) its expected identity
  comment, so both the linter (with full ``LinterContext``) and the
  formatter (with a lighter ``FormatterContext``) can share one code path.

Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- :func:`safe_parse` must not emit warnings to stderr; all warnings are
  returned as strings.
- :func:`safe_parse` must return ``None`` for the tree on ``SyntaxError``.
- :func:`header_boundary` must never raise; it returns an integer in
  ``[0, min(len(lines), 5)]``.
- :func:`header_boundary` must consume the trailing blank only if at
  least one header element was matched first.

Function Documentation

◆ header_boundary()

int parsing.header_boundary	(	list[str]	lines,
		Path	path,
		str \| None	expected_identity = None )

Return the line index where file content begins.

Scans at most the first 5 lines of *lines*, in strict order:
shebang → encoding → file-identity comment → blank line.

Parameters
----------
lines : list[str]
    Source file split by newlines (as returned by ``str.splitlines()``).
path : Path
    The file's path; its basename is used as the fallback identity
    match when *expected_identity* is not provided.
expected_identity : str | None, optional
    The exact expected file-identity comment (e.g.
    ``"# oct/core/parsing.py"``). When supplied the match is strict
    against this string; otherwise any ``"# ...<path.name>"`` line
    qualifies.

Definition at line 75 of file parsing.py.

◆ safe_parse()

tuple[ast.Module | None, list[str]] parsing.safe_parse ( str text )

Parse Python source, capturing SyntaxWarnings instead of emitting to stderr.

Returns (tree, warnings_list). tree is None on SyntaxError.

Definition at line 58 of file parsing.py.

Variable Documentation

◆ _ENCODING_RE

parsing._ENCODING_RE = re.compile(r"#.*coding[:=]")

protected

Definition at line 55 of file parsing.py.