arxpy 1.24.1__tar.gz

arxpy-1.24.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: arxpy
+Version: 1.24.1
+Summary: ArxPy is a Python API layer for the Arx compiler.
+License-Expression: Apache-2.0
+Author: Ivan Ogasawara
+Author-email: ivan.ogasawara@gmail.com
+Requires-Python: >=3.10,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: arxlang (==1.24.1)
+Description-Content-Type: text/markdown
+
+# ArxPy
+
+ArxPy is the developing Python-facing API for the Arx compiler.
+
+> Status: API foundation only. The package currently provides structured
+> diagnostics and public exception types; it does not yet expose parse, compile,
+> run, or artifact APIs.
+
+## Install
+
+```bash
+pip install arxpy
+```
+
+## Current API
+
+```python
+from arxpy import (
+    ArxError,
+    CompileError,
+    Diagnostic,
+    DiagnosticSeverity,
+    ExecutionError,
+    ParseError,
+)
+```
+
+`Diagnostic` is an immutable external record with severity, message, filename,
+line, column, and optional code. ArxPy adapters translate IRx structured
+diagnostics and Arx parser exceptions without exposing raw compiler nodes.
+
+All public failures inherit from `ArxError` and carry a `diagnostics` list.
+
+Until the compiler facade lands, use the `arx` CLI for end-to-end compilation or
+the lower-level Arx/IRx APIs for internal integrations.
+
+Documentation: <https://arxlang.org/arxpy/>
+
+License: Apache-2.0.
+

arxpy-1.24.1/README.md

@@ -0,0 +1,39 @@
+# ArxPy
+
+ArxPy is the developing Python-facing API for the Arx compiler.
+
+> Status: API foundation only. The package currently provides structured
+> diagnostics and public exception types; it does not yet expose parse, compile,
+> run, or artifact APIs.
+
+## Install
+
+```bash
+pip install arxpy
+```
+
+## Current API
+
+```python
+from arxpy import (
+    ArxError,
+    CompileError,
+    Diagnostic,
+    DiagnosticSeverity,
+    ExecutionError,
+    ParseError,
+)
+```
+
+`Diagnostic` is an immutable external record with severity, message, filename,
+line, column, and optional code. ArxPy adapters translate IRx structured
+diagnostics and Arx parser exceptions without exposing raw compiler nodes.
+
+All public failures inherit from `ArxError` and carry a `diagnostics` list.
+
+Until the compiler facade lands, use the `arx` CLI for end-to-end compilation or
+the lower-level Arx/IRx APIs for internal integrations.
+
+Documentation: <https://arxlang.org/arxpy/>
+
+License: Apache-2.0.

arxpy-1.24.1/pyproject.toml

@@ -0,0 +1,104 @@
+[project]
+name = "arxpy"
+version = "1.24.1"  # semantic-release
+description = "ArxPy is a Python API layer for the Arx compiler."
+readme = "README.md"
+authors = [
+  {name = "Ivan Ogasawara", email = "ivan.ogasawara@gmail.com"}
+]
+license = "Apache-2.0"
+requires-python = ">=3.10,<4"
+dependencies = [
+  "arxlang == 1.24.1",  # semantic-release
+]
+
+[build-system]
+requires = ["poetry-core>=2"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+exclude = [
+  ".git/*",
+  ".env*",
+]
+packages = [
+  {include = "arxpy", from="src"},
+]
+include = ["src/arxpy/py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+filterwarnings = [
+    "error::RuntimeWarning",
+]
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+targets = "./"
+
+[tool.vulture]
+exclude = ["tests"]
+ignore_decorators = ["abc.abstractmethod"]
+ignore_names = []
+make_whitelist = true
+min_confidence = 80
+paths = ["./"]
+sort_by_size = true
+verbose = false
+
+[tool.ruff]
+line-length = 79
+force-exclude = true
+src = ["./"]
+target-version = "py310"
+exclude = [
+  'docs',
+]
+fix = true
+
+[tool.ruff.lint]
+ignore = [
+  "F811",  # redefined-while-unused
+  "PLR2004",  # Magic value used in comparison
+  "PLR0911",  # Too many return statements
+  "PLR0912",  # Too many branches
+  "PLR0913",  # Too many arguments in a function definition
+  "PLR0917",  # Too many positional arguments
+  "RUF012",  # mutable-class-default
+  "PLR0915",  # Too many statements
+]
+select = [
+  "E",   # pycodestyle
+  "F",   # pyflakes
+  "YTT", # flake8-2020
+  "PL",  # PL
+  "RUF", # Ruff-specific rules
+  "I001", # isort
+]
+extend-select = [
+  "UP006",  # Prefer builtin generics in annotations
+  "UP007",  # Prefer | syntax for unions and optionals
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.isort]
+# Use a single line between direct and from import
+lines-between-types = 1
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"
+check_untyped_defs = true
+strict = true
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+show_error_codes = true
+exclude = ["scripts/"]

arxpy-1.24.1/src/arxpy/__init__.py

@@ -0,0 +1,43 @@
+"""
+title: Top-level package for ArxPy.
+"""
+
+from importlib import metadata as importlib_metadata
+
+from arxpy.diagnostics import Diagnostic, DiagnosticSeverity
+from arxpy.errors import (
+    ArxError,
+    CompileError,
+    ExecutionError,
+    ParseError,
+)
+
+_DISTRIBUTION_NAME = "arxpy"
+
+
+def get_version() -> str:
+    """
+    title: Return the program version.
+    returns:
+      type: str
+    """
+    try:
+        return importlib_metadata.version(_DISTRIBUTION_NAME)
+    except importlib_metadata.PackageNotFoundError:  # pragma: no cover
+        return "1.24.1"  # semantic-release
+
+
+__author__: str = "Ivan Ogasawara"
+__email__: str = "ivan.ogasawara@gmail.com"
+__version__: str = get_version()
+
+__all__ = [
+    "ArxError",
+    "CompileError",
+    "Diagnostic",
+    "DiagnosticSeverity",
+    "ExecutionError",
+    "ParseError",
+    "__version__",
+    "get_version",
+]

arxpy-1.24.1/src/arxpy/diagnostics.py

@@ -0,0 +1,183 @@
+"""
+title: Structured diagnostic records for the ArxPy public API.
+summary: >-
+  Define the stable, frozen Diagnostic record and the DiagnosticSeverity enum
+  that ArxPy exposes to callers, plus the duck-typed helpers that translate
+  upstream irx structured diagnostics and arx parser exceptions into it. The
+  Diagnostic type strips the astx.AST node reference that irx records carry, so
+  external callers never see raw compiler internals. These modules never import
+  arx or irx at module load time, so importing arxpy.diagnostics stays free of
+  the LLVM toolchain.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class DiagnosticSeverity(Enum):
+    """
+    title: Severity level of a diagnostic.
+    """
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    HINT = "hint"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """
+    title: One structured diagnostic exposed by the ArxPy API.
+    attributes:
+      severity:
+        type: DiagnosticSeverity
+        description: The severity level of the diagnostic.
+      message:
+        type: str
+        description: The human-readable diagnostic message.
+      filename:
+        type: str
+        description: Source attribution, or "<string>" / "<unknown>".
+      line:
+        type: int | None
+        description: One-based source line, when known.
+      column:
+        type: int | None
+        description: One-based source column, when known.
+      code:
+        type: str | None
+        description: Stable diagnostic code, e.g. "S001", when known.
+    """
+
+    severity: DiagnosticSeverity
+    message: str
+    filename: str
+    line: int | None
+    column: int | None
+    code: str | None = None
+
+
+def _coerce_severity(value: object) -> DiagnosticSeverity:
+    """
+    title: Coerce an upstream severity value into a DiagnosticSeverity.
+    summary: >-
+      Current irx diagnostics expose severity as a plain string such as
+      "error"; enum-like values exposing `.value` are also handled.
+      Unrecognised values fall back to ERROR.
+    parameters:
+      value:
+        type: object
+    returns:
+      type: DiagnosticSeverity
+    """
+    if isinstance(value, DiagnosticSeverity):
+        return value
+    raw = getattr(value, "value", value)
+    try:
+        return DiagnosticSeverity(str(raw))
+    except ValueError:
+        return DiagnosticSeverity.ERROR
+
+
+def _resolve_source(record: object) -> object | None:
+    """
+    title: Return the best-effort source location of an irx diagnostic.
+    parameters:
+      record:
+        type: object
+    returns:
+      type: object | None
+    """
+    resolver = getattr(record, "resolved_source", None)
+    if callable(resolver):
+        resolved: object = resolver()
+        return resolved
+    source: object = getattr(record, "source", None)
+    return source
+
+
+def _resolve_module_key(record: object) -> str | None:
+    """
+    title: Return the best-effort module attribution of an irx diagnostic.
+    parameters:
+      record:
+        type: object
+    returns:
+      type: str | None
+    """
+    resolver = getattr(record, "resolved_module_key", None)
+    if callable(resolver):
+        module_key = resolver()
+    else:
+        module_key = getattr(record, "module_key", None)
+    return None if module_key is None else str(module_key)
+
+
+def _from_irx(
+    record: object,
+    *,
+    filename: str | None = None,
+) -> Diagnostic:
+    """
+    title: Translate one irx structured diagnostic into an ArxPy Diagnostic.
+    summary: >-
+      Reads the upstream record by attribute so it accepts any irx.diagnostics
+      Diagnostic without importing irx, and discards the astx.AST node
+      reference. The current irx SourceLocation carries no filename, so the
+      attribution falls back to an explicit filename, then the diagnostic's
+      module key, then "<unknown>".
+    parameters:
+      record:
+        type: object
+      filename:
+        type: str | None
+    returns:
+      type: Diagnostic
+    """
+    source = _resolve_source(record)
+    code = getattr(record, "code", None)
+    attribution = filename or _resolve_module_key(record) or "<unknown>"
+    return Diagnostic(
+        severity=_coerce_severity(getattr(record, "severity", "error")),
+        message=str(getattr(record, "message", record)),
+        filename=attribution,
+        line=getattr(source, "line", None),
+        column=getattr(source, "col", None),
+        code=None if code is None else str(code),
+    )
+
+
+def _from_parser_exception(
+    exc: object,
+    *,
+    filename: str = "<string>",
+) -> Diagnostic:
+    """
+    title: Translate an arx ParserException into an ArxPy Diagnostic.
+    summary: >-
+      ParserException.__init__ discards the offending token's location, so line
+      and column are None by design rather than fabricated.
+    parameters:
+      exc:
+        type: object
+      filename:
+        type: str
+    returns:
+      type: Diagnostic
+    """
+    return Diagnostic(
+        severity=DiagnosticSeverity.ERROR,
+        message=str(exc),
+        filename=filename,
+        line=None,
+        column=None,
+    )
+
+
+__all__ = [
+    "Diagnostic",
+    "DiagnosticSeverity",
+]

arxpy-1.24.1/src/arxpy/errors.py

@@ -0,0 +1,93 @@
+"""
+title: Public exception hierarchy for the ArxPy API.
+summary: >-
+  Define the single error hierarchy ArxPy raises to callers: ArxError as the
+  base, with ParseError, CompileError, and ExecutionError for the lex/parse,
+  analysis/lowering, and execution stages of the pipeline. Each error carries a
+  list of structured Diagnostic records so callers can inspect failures
+  programmatically instead of scraping message text. The pipeline modules catch
+  upstream arx and irx exceptions and re-raise them as these types, building
+  diagnostics via the helpers in arxpy.diagnostics.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from arxpy.diagnostics import Diagnostic
+
+
+class ArxError(Exception):
+    """
+    title: Base class for every error raised by the ArxPy API.
+    attributes:
+      diagnostics:
+        type: list[Diagnostic]
+        description: Structured diagnostics describing the failure.
+    """
+
+    diagnostics: list[Diagnostic]
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        diagnostics: Sequence[Diagnostic] | None = None,
+    ) -> None:
+        """
+        title: Initialize an ArxError.
+        parameters:
+          message:
+            type: str
+          diagnostics:
+            type: Sequence[Diagnostic] | None
+        """
+        self.diagnostics = list(diagnostics or ())
+        super().__init__(message)
+
+
+class ParseError(ArxError):
+    """
+    title: Raised when lexing or parsing Arx source fails.
+    summary: >-
+      Parser-origin diagnostics have no line or column in v1 because
+      ParserException discards token location.
+    attributes:
+      diagnostics:
+        type: list[Diagnostic]
+    """
+
+
+class CompileError(ArxError):
+    """
+    title: >-
+      Raised when semantic analysis, lowering, native compile, or linking
+      fails.
+    summary: >-
+      Carries the structured diagnostics from the irx error family, which
+      include source locations for most phases.
+    attributes:
+      diagnostics:
+        type: list[Diagnostic]
+    """
+
+
+class ExecutionError(ArxError):
+    """
+    title: Raised when running a compiled Arx program fails to execute.
+    summary: >-
+      Reserved for failures that prevent execution from completing, such as a
+      missing binary or a timeout. A program that runs to completion with a
+      non-zero exit code is reported as data, not raised.
+    attributes:
+      diagnostics:
+        type: list[Diagnostic]
+    """
+
+
+__all__ = [
+    "ArxError",
+    "CompileError",
+    "ExecutionError",
+    "ParseError",
+]