arxjit 1.24.1__tar.gz

arxjit-1.24.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: arxjit
+Version: 1.24.1
+Summary: ArxJIT is a developing Numba-style JIT frontend for the Arx compiler stack.
+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: astx (==1.24.1)
+Requires-Dist: plum-dispatch (>=2)
+Requires-Dist: pyirx (==1.24.1)
+Description-Content-Type: text/markdown
+
+# ArxJIT
+
+ArxJIT is the planned Numba-style route from a restricted subset of pure Python
+to ASTx, IRx, LLVM, and native callable code.
+
+> **Important:** native JIT compilation is not implemented yet. A decorated
+> function currently executes the original Python function.
+
+## Current API
+
+```python
+from arxjit import i64, jit
+
+
+@jit(signature=i64(i64, i64), cache=True)
+def add(left, right):
+    return left + right
+
+
+assert add(20, 22) == 42  # Python fallback today
+```
+
+Implemented foundations:
+
+- `@jit` and the `JitFunction` wrapper
+- scalar signatures: `i32`, `i64`, `f32`, `f64`, and `bool_`
+- robust function-source extraction with real-file locations
+- validation for the proposed scalar Python subset
+- structured diagnostics and public error types
+
+The validator accepts typed scalar arguments, arithmetic/comparison/Boolean
+expressions, single-target assignments, `if`/`else`, `while`, `for` over the
+builtin `range`, and `return`. It rejects unsupported constructs with one
+diagnostic per violation.
+
+Not implemented:
+
+- Python AST to ASTx lowering
+- IRx compilation or native function calls
+- runtime argument/result marshalling
+- signature inference and artifact caching
+- array, Tensor, or Apache Arrow signatures
+
+See the [staged design](https://arxlang.org/arxjit/design.html) for the
+Python-to-ASTx pipeline.
+
+License: Apache-2.0.
+

arxjit-1.24.1/README.md

@@ -0,0 +1,47 @@
+# ArxJIT
+
+ArxJIT is the planned Numba-style route from a restricted subset of pure Python
+to ASTx, IRx, LLVM, and native callable code.
+
+> **Important:** native JIT compilation is not implemented yet. A decorated
+> function currently executes the original Python function.
+
+## Current API
+
+```python
+from arxjit import i64, jit
+
+
+@jit(signature=i64(i64, i64), cache=True)
+def add(left, right):
+    return left + right
+
+
+assert add(20, 22) == 42  # Python fallback today
+```
+
+Implemented foundations:
+
+- `@jit` and the `JitFunction` wrapper
+- scalar signatures: `i32`, `i64`, `f32`, `f64`, and `bool_`
+- robust function-source extraction with real-file locations
+- validation for the proposed scalar Python subset
+- structured diagnostics and public error types
+
+The validator accepts typed scalar arguments, arithmetic/comparison/Boolean
+expressions, single-target assignments, `if`/`else`, `while`, `for` over the
+builtin `range`, and `return`. It rejects unsupported constructs with one
+diagnostic per violation.
+
+Not implemented:
+
+- Python AST to ASTx lowering
+- IRx compilation or native function calls
+- runtime argument/result marshalling
+- signature inference and artifact caching
+- array, Tensor, or Apache Arrow signatures
+
+See the [staged design](https://arxlang.org/arxjit/design.html) for the
+Python-to-ASTx pipeline.
+
+License: Apache-2.0.

arxjit-1.24.1/pyproject.toml

@@ -0,0 +1,106 @@
+[project]
+name = "arxjit"
+version = "1.24.1"  # semantic-release
+description = "ArxJIT is a developing Numba-style JIT frontend for the Arx compiler stack."
+readme = "README.md"
+authors = [
+  {name = "Ivan Ogasawara", email = "ivan.ogasawara@gmail.com"}
+]
+license = "Apache-2.0"
+requires-python = ">=3.10,<4"
+dependencies = [
+  "astx == 1.24.1",  # semantic-release
+  "pyirx == 1.24.1",  # semantic-release
+  "plum-dispatch >= 2",
+]
+
+[build-system]
+requires = ["poetry-core>=2"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+exclude = [
+  ".git/*",
+  ".env*",
+]
+packages = [
+  {include = "arxjit", from="src"},
+]
+include = ["src/arxjit/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/"]

arxjit-1.24.1/src/arxjit/__init__.py

@@ -0,0 +1,65 @@
+"""
+title: Top-level package for arxjit.
+"""
+
+from importlib import metadata as importlib_metadata
+
+from arxjit.core import JitFunction, jit
+from arxjit.diagnostics import Diagnostic, DiagnosticSeverity
+from arxjit.errors import (
+    ArxJitError,
+    SourceExtractionError,
+    UnsupportedSyntaxError,
+)
+from arxjit.source import ExtractedSource, extract_source
+from arxjit.types import (
+    Signature,
+    SigType,
+    bool_,
+    f32,
+    f64,
+    i32,
+    i64,
+)
+from arxjit.validation import validate
+
+_DISTRIBUTION_NAME = "arxjit"
+
+
+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__ = [
+    "ArxJitError",
+    "Diagnostic",
+    "DiagnosticSeverity",
+    "ExtractedSource",
+    "JitFunction",
+    "SigType",
+    "Signature",
+    "SourceExtractionError",
+    "UnsupportedSyntaxError",
+    "__version__",
+    "bool_",
+    "extract_source",
+    "f32",
+    "f64",
+    "get_version",
+    "i32",
+    "i64",
+    "jit",
+    "validate",
+]

arxjit-1.24.1/src/arxjit/core.py

@@ -0,0 +1,108 @@
+"""
+title: The @jit decorator, the public entry point of arxjit.
+summary: >-
+  Wraps a pure Python function so it can be compiled through the Arx stack. In
+  this first version the wrapper records the requested signature and falls back
+  to running the original Python function; real compilation lands in later
+  sprints.
+"""
+
+from __future__ import annotations
+
+import functools
+
+from typing import Any, Callable
+
+from arxjit.types import Signature
+
+PyFunc = Callable[..., Any]
+
+
+class JitFunction:
+    """
+    title: A callable wrapper around a @jit-decorated function.
+    attributes:
+      py_func:
+        description: The original, undecorated Python function.
+      signature:
+        description: The explicit signature, or None when not given.
+      cache:
+        description: Whether compiled artifacts should be cached.
+    """
+
+    def __init__(
+        self,
+        py_func: PyFunc,
+        signature: Signature | None = None,
+        cache: bool = False,
+    ) -> None:
+        """
+        title: Wrap a Python function for just-in-time compilation.
+        parameters:
+          py_func:
+            type: PyFunc
+            description: The function being decorated.
+          signature:
+            type: Signature | None
+            description: The explicit call signature, if provided.
+          cache:
+            type: bool
+            description: Whether to cache compiled artifacts.
+        """
+        self.py_func = py_func
+        self.signature = signature
+        self.cache = cache
+        functools.update_wrapper(self, py_func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        title: Run the function (Python fallback until compilation lands).
+        parameters:
+          args:
+            type: Any
+            description: Positional arguments forwarded to the function.
+            variadic: positional
+          kwargs:
+            type: Any
+            description: Keyword arguments forwarded to the function.
+            variadic: keyword
+        returns:
+          type: Any
+        """
+        return self.py_func(*args, **kwargs)
+
+
+def jit(
+    fn: PyFunc | None = None,
+    *,
+    signature: Signature | None = None,
+    cache: bool = False,
+) -> JitFunction | functools.partial[JitFunction]:
+    """
+    title: Compile a pure Python function through the Arx stack.
+    summary: >-
+      Usable bare as ``@jit`` or with options as ``@jit(signature=i64(i64,
+      i64), cache=True)``. Records the requested signature and returns a
+      callable wrapper. When called with options it returns a partial that
+      wraps the function next.
+    parameters:
+      fn:
+        type: PyFunc | None
+        description: The function to wrap, when used as a bare decorator.
+      signature:
+        type: Signature | None
+        description: The explicit call signature.
+      cache:
+        type: bool
+        description: Whether to cache compiled artifacts.
+    returns:
+      type: JitFunction | functools.partial[JitFunction]
+    """
+    if signature is not None and not isinstance(signature, Signature):
+        raise TypeError(
+            "jit(signature=...) must be a Signature, e.g. i64(i64, i64)"
+        )
+
+    if fn is not None:
+        return JitFunction(fn, signature=signature, cache=cache)
+    return functools.partial(JitFunction, signature=signature, cache=cache)

arxjit-1.24.1/src/arxjit/diagnostics.py

@@ -0,0 +1,88 @@
+"""
+title: Structured diagnostic records for arxjit.
+summary: >-
+  Define the frozen Diagnostic record and the DiagnosticSeverity enum that
+  arxjit uses to report problems found while extracting, validating, or
+  compiling a decorated Python function. Diagnostics point at the user's Python
+  source (the file and line of the decorated function), so messages stay
+  actionable without exposing compiler internals.
+"""
+
+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 reported by arxjit.
+    attributes:
+      severity:
+        type: DiagnosticSeverity
+        description: The severity level of the diagnostic.
+      message:
+        type: str
+        description: The human-readable diagnostic message.
+      filename:
+        type: str
+        description: >-
+          The file defining the decorated function, or "<unknown>" when the
+          source cannot be attributed.
+      line:
+        type: int | None
+        description: One-based source line in ``filename``, when known.
+      column:
+        type: int | None
+        description: >-
+          One-based Unicode character column in ``line``, when known. Python
+          AST ``col_offset`` values (zero-based UTF-8 byte offsets) must be
+          converted to this representation at the boundary that produces the
+          diagnostic, never stored raw.
+      code:
+        type: str | None
+        description: Stable diagnostic code, e.g. "AJ001", when assigned.
+    """
+
+    severity: DiagnosticSeverity
+    message: str
+    filename: str
+    line: int | None
+    column: int | None
+    code: str | None = None
+
+    def __str__(self) -> str:
+        """
+        title: Render the diagnostic as one human-readable line.
+        summary: >-
+          Format is ``file:line:column: severity: [code] message``. Unknown
+          location parts are omitted (a column is only rendered when the line
+          is also known), and an unset or empty code renders no bracket prefix.
+        returns:
+          type: str
+        """
+        location = self.filename
+        if self.line is not None:
+            location = f"{location}:{self.line}"
+            if self.column is not None:
+                location = f"{location}:{self.column}"
+        prefix = f"[{self.code}] " if self.code else ""
+        return f"{location}: {self.severity.value}: {prefix}{self.message}"
+
+
+__all__ = [
+    "Diagnostic",
+    "DiagnosticSeverity",
+]

arxjit-1.24.1/src/arxjit/errors.py

@@ -0,0 +1,80 @@
+"""
+title: Public exception hierarchy for arxjit.
+summary: >-
+  Define the single error hierarchy arxjit raises to callers: ArxJitError as
+  the base, with SourceExtractionError for functions whose source cannot be
+  retrieved and parsed, and UnsupportedSyntaxError for functions using Python
+  constructs outside the supported subset. Each error carries a list of
+  structured Diagnostic records so callers can inspect failures
+  programmatically instead of scraping message text.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from arxjit.diagnostics import Diagnostic
+
+
+class ArxJitError(Exception):
+    """
+    title: Base class for every error raised by arxjit.
+    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 ArxJitError.
+        parameters:
+          message:
+            type: str
+          diagnostics:
+            type: Sequence[Diagnostic] | None
+        """
+        self.diagnostics = list(diagnostics or ())
+        super().__init__(message)
+
+
+class SourceExtractionError(ArxJitError):
+    """
+    title: Raised when a decorated function's source cannot be extracted.
+    summary: >-
+      Covers the whole extraction stage, functions whose source cannot be
+      retrieved or cannot be parsed as a standalone function definition, such
+      as ones defined in the REPL, built with exec, implemented in C, or
+      lambdas. Constructs rejected after successful extraction raise
+      UnsupportedSyntaxError instead.
+    attributes:
+      diagnostics:
+        type: list[Diagnostic]
+    """
+
+
+class UnsupportedSyntaxError(ArxJitError):
+    """
+    title: Raised when a function uses Python outside the supported subset.
+    summary: >-
+      Carries one diagnostic per rejected construct, each pointing at the
+      offending source line, so a function with several unsupported constructs
+      reports all of them at once.
+    attributes:
+      diagnostics:
+        type: list[Diagnostic]
+    """
+
+
+__all__ = [
+    "ArxJitError",
+    "SourceExtractionError",
+    "UnsupportedSyntaxError",
+]