spice-lang 0.2.2__tar.gz

spice_lang-0.2.2/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: spice-lang
+Version: 0.2.2
+Summary: Python but with all the spice
+Author: Reclipse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Operating System :: OS Independent
+Requires-Python: >=3.8
+Requires-Dist: click>=8.0
+Requires-Dist: colorama>=0.4
+Requires-Dist: rites>=0.5.4
+Requires-Dist: multipledispatch>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: black>=25.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: installer>=0.7; extra == "dev"

spice_lang-0.2.2/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spice-lang"
+version = "0.2.2"
+description = "Python but with all the spice"
+authors = [
+    { name = "Reclipse" }
+]
+requires-python = ">=3.8"
+dependencies = [
+    "click>=8.0",
+    "colorama>=0.4",
+    "rites>=0.5.4",
+    "multipledispatch>=1.0.0",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9",
+    "pytest-cov>=7.0",
+    "black>=25.1",
+    "mypy>=1.0",
+    "build>=1.0",
+    "installer>=0.7",
+]
+
+[project.scripts]
+spicy = "spice.cli.cli_handler:from_cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spice*"]

spice_lang-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spice_lang-0.2.2/spice/__init__.py

@@ -0,0 +1,8 @@
+"""Spice compiler - A Python superset with static typing features."""
+from importlib.metadata import version
+
+from spice import cli, lexer, parser, transformer, errors, printils, compilation
+
+__version__ = version("spice-lang")
+
+__all__ = ["cli", "lexer", "parser", "transformer", "compilation", "errors", "printils"]

spice_lang-0.2.2/spice/annotations/__init__.py

@@ -0,0 +1,15 @@
+"""Spice annotation framework: compile-time processors and their registry.
+
+`@name` annotations are runtime (emitted as Python decorators by the transformer);
+`@!name` annotations are compile-time and handled here by registered processors.
+"""
+
+from spice.annotations.base import AnnotationProcessor
+from spice.annotations.registry import register, get_processor, all_processors
+
+__all__ = [
+    "AnnotationProcessor",
+    "register",
+    "get_processor",
+    "all_processors",
+]

spice_lang-0.2.2/spice/annotations/base.py

@@ -0,0 +1,24 @@
+"""Base class for compile-time annotation processors."""
+
+from abc import ABC, abstractmethod
+
+
+class AnnotationProcessor(ABC):
+    """A compile-time annotation handler.
+
+    Subclasses set `name` (matched against `@!name`) and optionally `targets`
+    (a tuple of AST node types it may annotate; empty means any declaration).
+    Annotation arguments bind to `process`'s keyword parameters, decorator-factory
+    style: `@!print_on_call(time_format="%H:%M:%S")` -> `process(..., time_format=...)`.
+
+    `process` mutates `node` in place (and may edit AST fields directly). The
+    annotation stage strips the annotation afterward.
+    """
+
+    name: str = ""
+    targets: tuple = ()  # allowed node types; () = any
+
+    @abstractmethod
+    def process(self, node, file, **kwargs) -> None:
+        """Apply this annotation to `node`. `file` is the SpiceFile (utilities live there)."""
+        raise NotImplementedError

spice_lang-0.2.2/spice/annotations/builtins/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in compile-time annotation processors.
+
+Importing this package registers all built-ins as a side effect.
+"""
+
+from spice.annotations.builtins import print_on_call  # noqa: F401  (registers @!print_on_call)

spice_lang-0.2.2/spice/annotations/builtins/print_on_call.py

@@ -0,0 +1,34 @@
+"""Built-in `@!print_on_call` compile-time annotation.
+
+Injects a timestamped log line at the top of the annotated function's body:
+
+    @!print_on_call(time_format="%H:%M:%S")
+    def greet(name: str) -> None { ... }
+
+becomes (roughly):
+
+    import datetime
+
+    def greet(name: str) -> None:
+        print(f"[{datetime.datetime.now().strftime('%H:%M:%S')}] greet called")
+        ...
+"""
+
+from spice.annotations import AnnotationProcessor, register
+from spice.parser.ast_nodes import FunctionDeclaration
+
+
+@register
+class PrintOnCall(AnnotationProcessor):
+    name = "print_on_call"
+    targets = (FunctionDeclaration,)
+
+    def process(self, node, file, *, time_format: str = "%H:%M:%S") -> None:
+        if node.body is None:
+            node.body = []
+
+        file.ensure_import("datetime")
+
+        timestamp = f"datetime.datetime.now().strftime({time_format!r})"
+        code = f'print(f"[{{{timestamp}}}] {node.name} called")'
+        node.body.insert(0, file.raw_python(code))

spice_lang-0.2.2/spice/annotations/registry.py

@@ -0,0 +1,26 @@
+"""Registry of compile-time annotation processors, keyed by name."""
+
+from spice.annotations.base import AnnotationProcessor
+
+_REGISTRY: dict[str, AnnotationProcessor] = {}
+
+
+def register(cls):
+    """Class decorator: instantiate the processor and register it by `name`."""
+    instance = cls()
+    if not getattr(instance, "name", ""):
+        raise ValueError(f"Annotation processor {cls.__name__} must define a non-empty 'name'")
+    if instance.name in _REGISTRY:
+        raise ValueError(f"Duplicate annotation processor registered for '@!{instance.name}'")
+    _REGISTRY[instance.name] = instance
+    return cls
+
+
+def get_processor(name: str):
+    """Return the registered processor for `name`, or None."""
+    return _REGISTRY.get(name)
+
+
+def all_processors() -> dict:
+    """A copy of the current registry."""
+    return dict(_REGISTRY)

spice_lang-0.2.2/spice/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI module for Spice language."""
+
+__all__ = []

spice_lang-0.2.2/spice/cli/cli_handler.py

@@ -0,0 +1,38 @@
+from spice.printils import spice_compiler_log, pipeline_log, spam_console
+from spice.compilation import BuildFlags, SpiceFile, SpicePipeline
+
+from typing import Optional
+from pathlib import Path
+
+import click
+
+@click.command()
+@click.argument('source', type=click.Path(exists=True))
+@click.option('-o', '--output', type=click.Path(), help='Output file (default: <source>.py)')
+@click.option('-e', '--emit', type=click.Choice(['py', 'pyx', 'exe']), default='py', help='Compilation target (default: py)')
+@click.option('-k', '--keep-intermidiates', is_flag=True, help='Keep intermidiates generated during compilation (only applies to exe emit)')
+@click.option('-c', '--check', is_flag=True, help='Check syntax without generating output')
+@click.option('-w', '--watch', is_flag=True, help='Watch file for changes. This option disables verbosity.')
+@click.option('-v', '--verbose', is_flag=True, help='Verbose output')
+@click.option('--runtime-checks', is_flag=True, help='Add runtime type checking to output')
+@click.version_option(package_name='spice-lang', prog_name='spicy')
+def from_cli(source: str, output: Optional[str], emit: str, keep_intermidiates: bool, check: bool, watch: bool, verbose: bool, runtime_checks: bool):
+    """Compile Spice (.spc) files to Python, Cython, or standalone executables."""
+    flags: BuildFlags = BuildFlags(
+        source=Path(source),
+        output=Path(output) if output else None,
+        emit=emit,
+        keep_intermidiates=keep_intermidiates,
+        check=check,
+        watch=watch,
+        verbose=verbose,
+        runtime_checks=runtime_checks
+    )
+    spam_console(flags.verbose)
+
+    spice_compiler_log.custom("spice", f"Compiling from entry point: {flags.source.resolve().as_posix()}")
+
+    spice_tree: SpiceFile = SpicePipeline.walk(flags.source, None, flags)
+    SpicePipeline.verify_and_write(spice_tree, flags)
+
+    spice_compiler_log.custom("spice", "Compilation finished successfully.")

spice_lang-0.2.2/spice/compilation/__init__.py

@@ -0,0 +1,8 @@
+"""Compilation module for Spice"""
+
+from spice.compilation.build_flags import BuildFlags
+from spice.compilation.spicefile import SpiceFile
+from spice.compilation.pipeline import SpicePipeline
+from spice.compilation import checks
+
+__all__ = ["checks", "BuildFlags", "SpiceFile", "SpicePipeline"]

spice_lang-0.2.2/spice/compilation/build_flags.py

@@ -0,0 +1,105 @@
+"""Build configuration for the Spice compiler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _core_field(key: str) -> property:
+    """Build a get/set wrapper (property) for a core field backed by `_data`."""
+    def getter(self: "BuildFlags") -> Any:
+        return self._data.get(key)
+
+    def setter(self: "BuildFlags", value: Any) -> None:
+        self._data[key] = value
+
+    getter.__name__ = key
+    return property(getter, setter, doc=f"Core build flag '{key}'.")
+
+
+class BuildFlags:
+    """Compiler build options.
+
+    Core fields:
+        source: Path to the source .spc file or a directory with __main__.spc
+        output: Output directory or file path
+        emit: Compilation target ('py', 'pyx', or 'exe')
+        keep_intermediates: Keep intermediates generated during exe compilation
+        check: Syntax validation without code generation
+        watch: File watching mode
+        verbose: Detailed logging of pipeline stages
+        runtime_checks: Inject runtime type checking decorators
+
+    Extra keys (for plugins/tools) live in the same dict and are reached with
+    get()/set(), item access (flags["key"]) or as_dict().
+    """
+
+    CORE_DEFAULTS: dict[str, Any] = {
+        "source": None,
+        "output": None,
+        "emit": "py",
+        "keep_intermediates": False,
+        "check": False,
+        "watch": False,
+        "verbose": False,
+        "runtime_checks": False,
+    }
+
+    def __init__(
+        self,
+        source: Path,
+        output: Optional[Path] = None,
+        emit: str = "py",
+        keep_intermidiates: bool = False,
+        check: bool = False,
+        watch: bool = False,
+        verbose: bool = False,
+        runtime_checks: bool = False,
+        **extra: Any,
+    ) -> None:
+        self._data: dict[str, Any] = dict(self.CORE_DEFAULTS)
+        self._data.update({
+            "source": source,
+            "output": output,
+            "emit": emit,
+            "keep_intermediates": keep_intermidiates,
+            "check": check,
+            "watch": watch,
+            "verbose": verbose,
+            "runtime_checks": runtime_checks,
+        })
+
+        self._data.update(extra)
+
+    source = _core_field("source")
+    output = _core_field("output")
+    emit = _core_field("emit")
+    keep_intermediates = _core_field("keep_intermediates")
+    check = _core_field("check")
+    watch = _core_field("watch")
+    verbose = _core_field("verbose")
+    runtime_checks = _core_field("runtime_checks")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> "BuildFlags":
+        self._data[key] = value
+        return self
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._data[key] = value
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def as_dict(self) -> dict[str, Any]:
+        """A shallow copy of the backing dict (core fields + extras)."""
+        return dict(self._data)
+
+    def __repr__(self) -> str:
+        return f"BuildFlags({self._data!r})"

spice_lang-0.2.2/spice/compilation/checks/__init__.py

@@ -0,0 +1,22 @@
+"""Compile time checks for Spice source code."""
+
+from spice.compilation.checks.final_checker import FinalChecker
+from spice.compilation.checks.interface_checker import InterfaceChecker, CheckError
+from spice.compilation.checks.method_overload_resolver import MethodOverloadResolver
+from spice.compilation.checks.compile_time_check import CompileTimeCheck
+from spice.compilation.checks.symbol_table_builder import SymbolTableBuilder
+from spice.compilation.checks.type_checker import TypeChecker
+from spice.compilation.checks.generic_bound_checker import GenericBoundChecker
+from spice.compilation.checks.annotation_stage import AnnotationStage
+
+__all__ = [
+    "CheckError",
+    "FinalChecker",
+    "InterfaceChecker",
+    "MethodOverloadResolver",
+    "SymbolTableBuilder",
+    "TypeChecker",
+    "GenericBoundChecker",
+    "CompileTimeCheck",
+    "AnnotationStage",
+]

spice_lang-0.2.2/spice/compilation/checks/annotation_stage.py

@@ -0,0 +1,87 @@
+"""Annotation lowering stage.
+
+Runs compile-time (`@!`) annotation processors over the AST, strips the
+processed annotations, and leaves runtime (`@`) annotations in place for the
+transformer to emit as decorators. Implemented as a `CompileTimeCheck` so it
+plugs into the pipeline and reports fatal errors the usual way.
+"""
+
+import inspect
+
+from spice.compilation.checks.compile_time_check import CompileTimeCheck
+from spice.parser.ast_nodes import LiteralExpression
+from spice.annotations import get_processor
+import spice.annotations.builtins
+
+
+class AnnotationStage(CompileTimeCheck):
+    def __init__(self):
+        self.errors = []
+
+    def check(self, file) -> bool:
+        self.errors = []
+
+        # Comp time processors are able to modify the code so we need to materialize nodes first
+        for node in list(file.walk()):
+            if getattr(node, "annotations", None):
+                self._process_node(node, file)
+
+        self.errors.extend(getattr(file, "diagnostics", []))
+        return not self.errors
+
+    def _process_node(self, node, file) -> None:
+        remaining = []
+        for ann in node.annotations:
+            if ann.retention != "compile_time":
+                remaining.append(ann)  # runtime: left for the transformer
+                continue
+            self._apply(ann, node, file)  # compile-time: applied, then stripped
+        node.annotations = remaining
+
+    def _apply(self, ann, node, file) -> None:
+        proc = get_processor(ann.name)
+        if proc is None:
+            self.errors.append(f"Unknown compile-time annotation '@!{ann.name}' (line {ann.line})")
+            return
+
+        if proc.targets and not isinstance(node, proc.targets):
+            allowed = ", ".join(t.__name__ for t in proc.targets)
+            self.errors.append(
+                f"'@!{ann.name}' cannot annotate {type(node).__name__}; allowed: {allowed} (line {ann.line})"
+            )
+            return
+
+        try:
+            values = [self._literal(a) for a in ann.args]
+            kwargs = {key: self._literal(value) for key, value in ann.kwargs.items()}
+        except TypeError as exc:
+            self.errors.append(f"'@!{ann.name}': {exc} (line {ann.line})")
+            return
+
+        # Validate arity / names against process(node, file, **bound) before any side effects.
+        try:
+            inspect.signature(proc.process).bind(node, file, *values, **kwargs)
+        except TypeError as exc:
+            self.errors.append(f"'@!{ann.name}': {exc} (line {ann.line})")
+            return
+
+        proc.process(node, file, *values, **kwargs)
+
+    def _literal(self, expr):
+        """Evaluate a compile-time-literal argument expression to a Python value."""
+        if not isinstance(expr, LiteralExpression):
+            raise TypeError(f"argument must be a compile-time literal, got {type(expr).__name__}")
+
+        lt = expr.literal_type
+        value = expr.value
+        if lt == "number":
+            text = str(value)
+            return float(text) if ("." in text or "e" in text.lower()) else int(text)
+        if lt in ("string", "fstring"):
+            s = str(value)
+            if len(s) >= 2 and s[0] == s[-1] and s[0] in "\"'":
+                s = s[1:-1]
+            return s
+        if lt == "boolean":
+            return bool(value)
+        return value

spice_lang-0.2.2/spice/compilation/checks/compile_time_check.py

@@ -0,0 +1,16 @@
+from abc import ABC, abstractmethod
+from spice.compilation.spicefile import SpiceFile
+
+class CompileTimeCheck(ABC):
+    @abstractmethod
+    def check(self, file: SpiceFile) -> bool:
+        """Perform the compile-time check on the given SpiceFile.
+        
+        Args:
+            file (SpiceFile): The Spice file to check.
+        
+        Returns:
+            bool: True if the check passes, False otherwise.
+        """
+        pass
+    

spice_lang-0.2.2/spice/compilation/checks/final_checker.py

@@ -0,0 +1,189 @@
+from dataclasses import fields, is_dataclass
+from typing import Dict, List, Optional, Set, TYPE_CHECKING, Union
+
+from spice.parser.ast_nodes import (
+    ASTNode,
+    AssignmentExpression,
+    ClassDeclaration,
+    ExpressionStatement,
+    FinalDeclaration,
+    FunctionDeclaration,
+    IdentifierExpression,
+)
+from spice.compilation.checks.compile_time_check import CompileTimeCheck
+from spice.compilation.checks.interface_checker import CheckError
+
+if TYPE_CHECKING:
+    from spice.compilation.spicefile import SpiceFile
+
+class FinalChecker(CompileTimeCheck):
+    """Compile-time checker for final variable reassignments."""
+
+    def __init__(self):
+        self._reset_state()
+
+    def _reset_state(self):
+        self.final_variables: Dict[str, Set[str]] = {'global': set()}
+        self.current_scope = 'global'
+        self.errors: List[Union[str, CheckError]] = []
+        self.class_nodes: Dict[str, ClassDeclaration] = {}
+        self.final_methods_by_class: Dict[str, Dict[str, FunctionDeclaration]] = {}
+
+    def check(self, file: "SpiceFile") -> bool:
+        self._reset_state()
+        self._collect_class_metadata(file.ast.body)
+        for node in file.ast.body:
+            self._visit_node(node)
+        return not self.errors
+
+
+    def enter_scope(self, scope_name: str):
+        """Enter a new scope (function/class)."""
+        self.current_scope = scope_name
+        if scope_name not in self.final_variables:
+            self.final_variables[scope_name] = set()
+
+    def exit_scope(self):
+        """Exit current scope."""
+        self.current_scope = 'global'
+
+    def register_final(self, var_name: str):
+        """Register a variable as final in current scope."""
+        if self.current_scope not in self.final_variables:
+            self.final_variables[self.current_scope] = set()
+        self.final_variables[self.current_scope].add(var_name)
+
+    def check_assignment(self, var_name: str, line: int = 0, column: int = 0):
+        """Check if assignment to variable is allowed."""
+        scope_vars = self.final_variables.get(self.current_scope, set())
+        global_vars = self.final_variables.get('global', set())
+
+        if var_name in scope_vars or var_name in global_vars:
+            self.errors.append(CheckError(
+                message=f"Cannot reassign final variable '{var_name}'",
+                line=line,
+                column=column
+            ))
+            return False
+        return True
+
+    def _visit_node(self, node):
+        """Visit a node and check for violations."""
+        if isinstance(node, FinalDeclaration):
+            if isinstance(node.target, IdentifierExpression):
+                self.register_final(node.target.name)
+
+        elif isinstance(node, ExpressionStatement):
+            self._visit_expression(node.expression)
+        elif isinstance(node, AssignmentExpression):
+            self._handle_assignment(node)
+        elif isinstance(node, FunctionDeclaration):
+            old_scope = self.current_scope
+            self.enter_scope(node.name)
+            for stmt in node.body:
+                self._visit_node(stmt)
+            self.current_scope = old_scope
+
+        elif isinstance(node, ClassDeclaration):
+            old_scope = self.current_scope
+            self.enter_scope(node.name)
+            self._check_final_method_overrides(node)
+            for member in node.body:
+                self._visit_node(member)
+            self.current_scope = old_scope
+
+        if hasattr(node, 'body') and isinstance(node.body, list):
+            for child in node.body:
+                self._visit_node(child)
+
+    def _visit_expression(self, expr: Optional[ASTNode]):
+        """Traverse expressions searching for assignments."""
+        if expr is None:
+            return
+
+        if isinstance(expr, AssignmentExpression):
+            self._handle_assignment(expr)
+
+        if is_dataclass(expr):
+            for field in fields(expr):
+                value = getattr(expr, field.name)
+                self._visit_expression_field(value)
+
+    def _visit_expression_field(self, value):
+        if isinstance(value, list):
+            for item in value:
+                if isinstance(item, ASTNode):
+                    self._visit_expression(item)
+        elif isinstance(value, ASTNode):
+            self._visit_expression(value)
+
+    def _handle_assignment(self, node: AssignmentExpression):
+        if isinstance(node.target, IdentifierExpression):
+            self.check_assignment(node.target.name, node.line, node.column)
+        self._visit_expression(node.value)
+
+    def _collect_class_metadata(self, nodes: List[ASTNode]):
+        """Collect class declarations and their final methods for later checks."""
+        for node in nodes:
+            if isinstance(node, ClassDeclaration):
+                self.class_nodes[node.name] = node
+
+                final_methods = {
+                    member.name: member
+                    for member in node.body
+                    if isinstance(member, FunctionDeclaration) and member.is_final
+                }
+                if final_methods:
+                    self.final_methods_by_class[node.name] = final_methods
+
+                self._collect_class_metadata(node.body)
+            elif hasattr(node, 'body') and isinstance(node.body, list):
+                self._collect_class_metadata(node.body)
+
+    def _check_final_method_overrides(self, class_node: ClassDeclaration):
+        """Ensure subclasses do not override final methods declared in parents."""
+        inherited_final_methods = self._collect_inherited_final_methods(class_node)
+        if not inherited_final_methods:
+            return
+
+        for member in class_node.body:
+            if isinstance(member, FunctionDeclaration) and member.name in inherited_final_methods:
+                base_name = inherited_final_methods[member.name]
+                self.errors.append(CheckError(
+                    message=f"Class '{class_node.name}' cannot override final method '{member.name}' defined in '{base_name}'",
+                    line=member.line,
+                    column=member.column
+                ))
+
+    def _collect_inherited_final_methods(self, class_node: ClassDeclaration) -> Dict[str, str]:
+        """Gather final methods from all parent classes."""
+        inherited: Dict[str, str] = {}
+
+        for base_name in class_node.bases:
+            base_methods = self._collect_final_methods_from_base(base_name, set())
+            for method_name, origin in base_methods.items():
+                inherited.setdefault(method_name, origin)
+
+        return inherited
+
+    def _collect_final_methods_from_base(self, base_name: str, visited: Set[str]) -> Dict[str, str]:
+        """Collect final methods from the given base class and its parents."""
+        if base_name in visited:
+            return {}
+
+        visited.add(base_name)
+        methods: Dict[str, str] = {
+            method_name: base_name
+            for method_name in self.final_methods_by_class.get(base_name, {})
+        }
+
+        base_node = self.class_nodes.get(base_name)
+        if not base_node:
+            return methods
+
+        for ancestor in base_node.bases:
+            ancestor_methods = self._collect_final_methods_from_base(ancestor, set(visited))
+            for method_name, origin in ancestor_methods.items():
+                methods.setdefault(method_name, origin)
+
+        return methods