arxjit.source

arxjit.source

Source: packages/arxjit/src/arxjit/source.py

title: Source extraction for @jit-decorated Python functions.
summary: >-
  First stage of the arxjit pipeline: retrieve the source of a decorated
  function, parse it with Python's built-in ast module, and drop the
  decorators. The source text is never modified: an indented definition (a
  nested function or a method) is parsed inside a synthetic "if True:" wrapper
  instead of being dedented, which preserves string literal content and keeps
  every node's line and column pointing into the real file. Every failure
  raises SourceExtractionError carrying structured diagnostics; validating the
  parsed body against the supported Python subset is a later stage and is not
  done here.

Functions

extract_source(fn: PyFunc) -> ExtractedSource

title: Extract and parse the source of a decorated function.
summary: >-
  Retrieves the source block with inspect.getsourcelines (which follows
  __wrapped__, so a JitFunction resolves to the function it wraps) and
  parses it with ast.parse. An indented block is parsed inside a synthetic
  "if True:" wrapper rather than dedented, so the text is never modified
  and every node keeps real file lines and columns. The decorators are
  dropped from the returned node and source; async definitions are
  extracted here and left for the validation stage to accept or reject.
parameters:
  fn:
    type: PyFunc
    description: The Python function to extract.
returns:
  type: ExtractedSource
raises:
  SourceExtractionError: >-
    If the source cannot be retrieved (REPL- or exec-defined functions, C
    builtins, self-referential wrappers, or a corrupted or since-modified
    source file), cannot be parsed (including source containing null
    bytes), or is not a single function definition (for example a lambda).

Classes

ExtractedSource

title: The extracted source of a decorated function.
attributes:
  filename:
    type: str
    description: The file defining the function, or "<unknown>".
  source:
    type: str
    description: >-
      Verbatim file text of the function definition with the decorator
      lines removed; the first line is the def statement, and the original
      indentation is preserved so string literals are untouched.
  lineno:
    type: int
    description: One-based line of the def statement in ``filename``.
  node:
    type: ast.FunctionDef | ast.AsyncFunctionDef
    description: >-
      The parsed function definition with an empty decorator list. Line
      numbers match ``filename``, so they can be reported in diagnostics
      directly. Column offsets are raw ast ``col_offset`` values (zero-
      based UTF-8 byte offsets) that point into the real file line, because
      the source is parsed without modifying its indentation; only the
      byte-to-character conversion is needed at the boundary that produces
      a diagnostic.
  globalns:
    type: Mapping[str, Any] | None
    description: >-
      The module namespace the function was defined in, or None when the
      object has no globals. Carried so later stages can detect module-
      level shadowing of a name the compiler treats as a builtin, which the
      AST alone cannot reveal. Excluded from repr and equality: it is
      incidental runtime context, not part of the extracted source.
  freevars:
    type: frozenset[str]
    description: >-
      The names the function captures from enclosing scopes, empty when it
      captures nothing. Carried for the same reason as ``globalns``: a
      captured name is indistinguishable from a builtin in the AST alone.
  qualname:
    type: str
    description: >-
      The function's __qualname__, or "" when the object has none. Carried
      for the same reason as ``globalns``: a method is an ordinary function
      in the AST, and only the qualified name records the class it was
      defined in. It records the *definition site*, not which class owns
      the descriptor now, so it cannot reveal a function assigned into a
      class body or attached to a class afterwards.