arxpy.compiler

`arxpy.compiler`

Source: packages/arxpy/src/arxpy/compiler.py

title: Typed programmatic facade for the Arx compiler pipeline.
summary: >-
  Provide parse, check, compile, artifact, and execution APIs without exposing
  CLI state. Heavy frontend, semantic, and LLVM modules are imported only when
  an operation needs them, keeping `import arxpy` lightweight. Compiler
  operations are serialized because the current Arx lexer reads a process-wide
  source buffer; each lowering operation uses a fresh backend builder.

Functions

`api_diagnostic(message: str, *, filename: str, code: str) -> Diagnostic`

title: Build one facade-originated error diagnostic.
parameters:
  message:
    type: str
  filename:
    type: str
  code:
    type: str
returns:
  type: Diagnostic

`compile_diagnostics(error: object, *, filename: str) -> list[Diagnostic]`

title: Translate a structured IRx failure into public diagnostics.
parameters:
  error:
    type: object
  filename:
    type: str
returns:
  type: list[Diagnostic]

`has_imports(module: astx.Module) -> bool`

title: Return whether a parsed module contains source imports.
parameters:
  module:
    type: astx.Module
returns:
  type: bool

`has_main(module: astx.Module) -> bool`

title: Return whether a module defines the executable entry point.
parameters:
  module:
    type: astx.Module
returns:
  type: bool

`program_context(program: ParsedProgram) -> tuple[ParsedModule, ImportResolver] | None`

title: Build import and native capabilities from a program's origin.
parameters:
  program:
    type: ParsedProgram
returns:
  type: tuple[ParsedModule, ImportResolver] | None

`resolved_output_path(program: ParsedProgram, kind: ArtifactKind, output: str | Path | None) -> Path`

title: Resolve a caller-owned materialized artifact path.
parameters:
  program:
    type: ParsedProgram
  kind:
    type: ArtifactKind
  output:
    type: str | Path | None
returns:
  type: Path

Classes

`ArtifactKind(Enum)`

title: Kind of output requested from the compiler.

`ParsedProgram`

title: Parsed Arx source plus stable source attribution.
attributes:
  module:
    type: astx.Module
  source:
    type: str
  filename:
    type: str
  module_name:
    type: str
  origin:
    type: Path | None
  has_source_imports:
    type: bool

`CheckedProgram`

title: Program that completed semantic analysis successfully.
attributes:
  parsed:
    type: ParsedProgram

`CompilationArtifact`

title: Materialized compiler output.
attributes:
  kind:
    type: ArtifactKind
  path:
    type: Path | None
  llvm_ir:
    type: str | None

`ExecutionResult`

title: Captured result of running an executable artifact.
attributes:
  exit_code:
    type: int
  stdout:
    type: str
  stderr:
    type: str

`Compiler`

title: Reusable facade for parse, check, compile, and run operations.
summary: >-
  Operations are safe to repeat and serialized across Compiler instances
  while the frontend uses its process-wide input buffer. The facade never
  creates an implicit temporary artifact: callers provide an output path
  for in-memory compilation, while file compilation defaults beside the
  source. Unknown internal exceptions are not hidden as user diagnostics.

Methods

`parse_string(self, source: str, *, filename: str='<string>', module_name: str='main') -> ParsedProgram`

title: Parse Arx source text.
parameters:
  source:
    type: str
  filename:
    type: str
  module_name:
    type: str
returns:
  type: ParsedProgram

`parse_file(self, path: str | Path) -> ParsedProgram`

title: Read and parse one UTF-8 Arx source file.
parameters:
  path:
    type: str | Path
returns:
  type: ParsedProgram

`check(self, program: ParsedProgram) -> CheckedProgram`

title: Run semantic analysis without lowering or materialization.
parameters:
  program:
    type: ParsedProgram
returns:
  type: CheckedProgram

`compile(self, program: ParsedProgram | CheckedProgram, *, kind: ArtifactKind=ArtifactKind.AUTO, output: str | Path | None=None, link_mode: Literal['auto', 'pie', 'no-pie']='auto') -> CompilationArtifact`

title: Lower a program and optionally materialize a host artifact.
parameters:
  program:
    type: ParsedProgram | CheckedProgram
  kind:
    type: ArtifactKind
  output:
    type: str | Path | None
  link_mode:
    type: Literal[auto, pie, no-pie]
returns:
  type: CompilationArtifact

`compile_file(self, path: str | Path, *, kind: ArtifactKind=ArtifactKind.AUTO, output: str | Path | None=None, link_mode: Literal['auto', 'pie', 'no-pie']='auto') -> CompilationArtifact`

title: Parse and compile one source file.
parameters:
  path:
    type: str | Path
  kind:
    type: ArtifactKind
  output:
    type: str | Path | None
  link_mode:
    type: Literal[auto, pie, no-pie]
returns:
  type: CompilationArtifact

`run(self, artifact: CompilationArtifact, *, args: Sequence[str]=(), cwd: str | Path | None=None, env: Mapping[str, str] | None=None, timeout: float | None=None) -> ExecutionResult`

title: Run an executable artifact without invoking a shell.
parameters:
  artifact:
    type: CompilationArtifact
  args:
    type: Sequence[str]
  cwd:
    type: str | Path | None
  env:
    type: Mapping[str, str] | None
  timeout:
    type: float | None
returns:
  type: ExecutionResult