Metadata-Version: 2.2
Name: elaraai-east-py
Version: 1.0.1
Summary: Python runtime for the East programming language
Keywords: east,embedded,language,runtime,interpreter
Author-Email: East Contributors <east@example.com>
License: # Business Source License 1.1
         
         Copyright (c) 2025 Elara AI Pty Ltd
         
         ## License
         
         **Licensor:** Elara AI Pty Ltd
         
         **Licensed Work:** @elaraai/east-py
         
         **Change Date:** Four years from the date of each release
         
         **Change License:** AGPL-3.0
         
         ## Terms
         
         The Licensed Work is provided under the terms of the Business Source License 1.1 as detailed below.
         
         ### Grant of Rights
         
         The Licensor grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.
         
         ### Production Use Limitation
         
         **"Production Use"** means any use by or on behalf of a for-profit entity, other than for evaluation, testing, or development purposes.
         
         Production Use requires a separate commercial license from the Licensor.
         
         ### Change Date
         
         On the Change Date (four years after each release), the Licensed Work will be made available under the Change License (AGPL-3.0).
         
         ### No Warranty
         
         THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
         
         ### Package-Specific Licenses
         
         Individual packages within this repository may have different licensing terms. See the LICENSE.md file in each package directory for details.
         
         ## Commercial Licensing
         
         To obtain a commercial license for Production Use, contact:
         
         **Email:** support@elara.ai
         **Website:** https://elaraai.com
         
         ## Governing Law
         
         This license is governed by the laws of New South Wales, Australia.
         
         ---
         
         *Elara AI Pty Ltd*
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Interpreters
Project-URL: Homepage, https://github.com/elaraai/east-py
Project-URL: Documentation, https://github.com/elaraai/east-py/tree/main/packages/east-py
Project-URL: Repository, https://github.com/elaraai/east-py
Project-URL: Issues, https://github.com/elaraai/east-py/issues
Requires-Python: >=3.11
Requires-Dist: sortedcontainers>=2.4.0
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: numpy>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pre-commit>=3.8.0; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.9; extra == "dev"
Provides-Extra: data
Requires-Dist: pandas>=2.0.0; extra == "data"
Provides-Extra: cython
Requires-Dist: cython>=3.0.0; extra == "cython"
Requires-Dist: setuptools>=69.0.0; extra == "cython"
Description-Content-Type: text/markdown

# East.py

[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-orange.svg)](LICENSE.md)

Python runtime for the [East programming language](https://github.com/elaraai/east-workspace/tree/main/libs/east).

## Overview

East.py is a Python backend that enables East IR to be compiled and executed in Python environments. It provides:

- **Complete type system** - Full representation of all East types (primitives, containers, structs, variants, functions)
- **IR compiler** - Compiles East IR nodes to executable Python functions
- **212+ builtin functions** - Array, Set, Dict, String, DateTime, Blob, Integer, Float operations
- **Serialization** - East text format, JSON, and BEAST (Binary East) support
- **DateTime formatting** - Custom datetime parsing and printing with format strings
- **Type analysis** - IR validation and type inference
- **Platform integration** - Embed East functions in Python applications

## Current Status

✅ **Fully Implemented:**
- Type system (all East types)
- IR builders and compiler
- 212 builtin functions (100% coverage)
- Serialization (East text, JSON, BEAST)
- DateTime formatting (parse/print)
- Type comparison and equality
- Container types (Array, Set, Dict)
- Platform integration API

**Test Coverage:** 980 tests passing, 84% code coverage

## Installation

```bash
# Install from source
git clone https://github.com/elaraai/east-workspace/tree/main/libs/east-py
cd east-py
pip install -e .
```

## Quick Start

Here's a complete example showing how to load, compile, and execute East IR with platform functions:

```python
import asyncio
import json
from east.runtime.compiler import compile_async
from east.runtime.platform import PlatformFunction
from east.serialization.json import decode_json_for
from east.types.type_system import IntegerType, IRType, NullType, StringType

# Load IR from a file (generated by East TypeScript compiler)
# In this example, the IR represents a function that:
# 1. Logs a message
# 2. Fetches HTTP status from a URL (async)
# 3. Logs the response with timing info
with open("fetch_status.ir.json") as f:
    ir_json = json.load(f)

# Decode IR from JSON to East IR nodes
decoder = decode_json_for(IRType)
ir_bytes = json.dumps(ir_json).encode("utf-8")
fetch_status_ir = decoder(ir_bytes)

# Define platform function implementations
def log_impl(message: str) -> None:
    """Sync platform function: log a message."""
    print(message)

async def fetch_status_impl(url: str) -> str:
    """Async platform function: fetch HTTP status from URL."""
    import urllib.request
    loop = asyncio.get_event_loop()
    response = await loop.run_in_executor(None, urllib.request.urlopen, url)
    return f"{response.status} ({response.msg})"

def time_ns_impl() -> int:
    """Sync platform function: get current time in nanoseconds."""
    import time
    return time.time_ns()

# Register platform functions with type signatures
platform = [
    PlatformFunction(
        name="log",
        inputs=[StringType],
        output=NullType,
        type="sync",
        fn=log_impl
    ),
    PlatformFunction(
        name="fetch_status",
        inputs=[StringType],
        output=StringType,
        type="async",
        fn=fetch_status_impl
    ),
    PlatformFunction(
        name="time_ns",
        inputs=[],
        output=IntegerType,
        type="sync",
        fn=time_ns_impl
    ),
]

# Compile IR to Python function (handles async automatically)
compiled_fn = compile_async(fetch_status_ir, platform)

# Execute the compiled function
async def main():
    await compiled_fn("https://www.google.com")
    # Output:
    # Fetching URL: https://www.google.com
    # Response status: 200 (OK) - fetched in 123.45 ms

if __name__ == "__main__":
    asyncio.run(main())
```

## Development

```bash
# First-time setup (installs dependencies and pre-commit hooks)
make install

# Development workflow
make test          # Run test suite
make lint          # Run linter (ruff)
make format        # Format code
make typecheck     # Type check with mypy
make check         # Run all checks (lint + typecheck + test)

# Other useful commands
make repl          # Start Python REPL with east loaded
make coverage      # Generate HTML coverage report
make lint-fix      # Auto-fix linting issues
make clean         # Clean build artifacts

# Run specific test suites (using uv)
uv run pytest tests/builtins/test_builtins.py -v
uv run pytest tests/serialization/test_json.py -v
uv run pytest tests/types/test_types.py -v

# Rebuild Cython extensions after modifying .pyx files
make build-cython
```

### Cython Acceleration

Performance-critical modules (BEAST2 deserialization, CSV parsing, struct/variant construction) have optional Cython acceleration. Extensions compile automatically during `pip install` / `uv sync` when a C compiler is available. Without one, the package falls back to pure Python with no error.

Requires `gcc` and `python3-dev` (Linux) or Xcode CLI tools (macOS).

## Architecture

### Module Structure

- `east/types/` - Type system implementation
  - `type_system.py` - Core type definitions and constructors
  - `primitives.py` - Null, Boolean, Integer, Float, String, Blob, DateTime
  - `containers.py` - Array, Set, Dict implementations
  - `structural.py` - Struct, Variant, Function types

- `east/builtins/` - Builtin function implementations
  - `array.py` - Array operations (map, filter, reduce, sort, search, etc.)
  - `set_ops.py` - Set operations (union, intersection, map, reduce, etc.)
  - `dict_ops.py` - Dict operations (map, filter, merge, etc.)
  - `string.py` - String operations (split, join, regex, JSON, etc.)
  - `datetime_ops.py` - DateTime operations (add, diff, compare, etc.)
  - `comparison.py` - Comparison and equality functions

- `east/serialization/` - Serialization formats
  - `east_parser.py` - Parse East text format
  - `east_printer.py` - Print East text format
  - `json.py` - JSON encoding/decoding
  - `beast.py` - Binary East format

- `east/ir/` - Intermediate representation
  - `builders.py` - Helper functions for building IR nodes
  - `analyze.py` - Type checking and validation

- `east/runtime/` - Execution engine
  - `compiler.py` - Compile IR to Python functions
  - `platform.py` - Platform integration API

- `east/datetime_format/` - DateTime formatting
  - `parse.py` - Parse datetime strings with format
  - `print.py` - Print datetime with format
  - `tokenize.py` - Format string tokenization


## Claude Code plugin

The East ecosystem also ships a [Claude Code](https://claude.com/claude-code) plugin — East language skills, example search, and preemptive diagnostics for East code — installed separately from the `elaraai` marketplace:

```text
# Inside Claude Code
/plugin marketplace add elaraai/east-workspace
/plugin install east@elaraai
```

```bash
# From a terminal
claude plugin marketplace add elaraai/east-workspace
claude plugin install east@elaraai
```

## License

**BSL 1.1 (Business Source License):**
- Non-production use (evaluation, testing, development) is free
- Production use by or on behalf of for-profit entities requires a commercial license
- Code becomes AGPL-3.0 four years after each release

See [LICENSE.md](LICENSE.md) for full details.

**Commercial licensing:** support@elara.ai

### Ecosystem

- **[East](https://github.com/elaraai/east-workspace/tree/main/libs/east)**: Statically typed, expression-based language with serializable IR. Run portable logic across TypeScript, Python, C, and other runtimes.
  - [@elaraai/east](https://www.npmjs.com/package/@elaraai/east): Core language SDK with type system, expressions, and reference JS compiler

- **[East Node](https://github.com/elaraai/east-workspace/tree/main/libs/east-node)**: Node.js platform functions for I/O, databases, and system operations.
  - [@elaraai/east-node-std](https://www.npmjs.com/package/@elaraai/east-node-std): Console, FileSystem, Fetch, Crypto, Time, Path, Random
  - [@elaraai/east-node-io](https://www.npmjs.com/package/@elaraai/east-node-io): SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  - [@elaraai/east-node-cli](https://www.npmjs.com/package/@elaraai/east-node-cli): CLI for running East IR programs in Node.js

- **[East C](https://github.com/elaraai/east-workspace/tree/main/libs/east-c)**: C11 native runtime for executing East IR. Tarballed for `linux-x64` and `linux-arm64`, attached to each GitHub Release.
  - `east-c`: Core runtime — type system, IR interpreter, 200+ builtins, serialization (Beast2, JSON, CSV, East text)
  - `east-c-std`: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  - `east-c-cli`: CLI for running East IR programs natively

- **[East Python](https://github.com/elaraai/east-workspace/tree/main/libs/east-py)**: Python runtime, standard platform, I/O, and data-science platform functions. Published to PyPI.
  - [east-py](https://pypi.org/project/east-py/): Core Python runtime — type system, IR compiler, 212+ builtins, Cython-accelerated hot paths
  - [east-py-std](https://pypi.org/project/east-py-std/): Console, FileSystem, Fetch, Crypto, Time, Path, Random
  - [east-py-io](https://pypi.org/project/east-py-io/): SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  - [east-py-cli](https://pypi.org/project/east-py-cli/): CLI for running East IR programs in Python
  - [east-py-datascience](https://pypi.org/project/east-py-datascience/) (PyPI) + [@elaraai/east-py-datascience](https://www.npmjs.com/package/@elaraai/east-py-datascience) (npm): Optimization (MADS, Optuna, ALNS, GoogleOR), ML (XGBoost, LightGBM, NGBoost, PyTorch, Lightning, GP), Bayesian inference (PyMC), explainability (SHAP), conformal prediction (MAPIE)

- **[East UI](https://github.com/elaraai/east-workspace/tree/main/libs/east-ui)**: Typed UI component definitions and React renderer, plus VS Code preview.
  - [@elaraai/east-ui](https://www.npmjs.com/package/@elaraai/east-ui): 50+ typed UI components for layouts, forms, charts, tables, dialogs
  - [@elaraai/east-ui-components](https://www.npmjs.com/package/@elaraai/east-ui-components): React renderer with Chakra UI v3 styling
  - [@elaraai/e3-ui](https://www.npmjs.com/package/@elaraai/e3-ui): e3 + UI bridge — Data bindings, `e3.ui()` task, manifest
  - [@elaraai/e3-ui-components](https://www.npmjs.com/package/@elaraai/e3-ui-components): React Query hooks and preview components for the e3 API
  - [east-ui-preview](https://marketplace.visualstudio.com/items?itemName=ElaraAI.east-ui-preview): VS Code extension for live East UI component preview

- **[e3 — East Execution Engine](https://github.com/elaraai/east-workspace/tree/main/libs/e3)**: Durable execution engine for running East pipelines at scale. Git-like content-addressable storage, automatic memoization, reactive dataflow, real-time monitoring.
  - [@elaraai/e3](https://www.npmjs.com/package/@elaraai/e3): SDK for authoring e3 packages with typed tasks and pipelines
  - [@elaraai/e3-core](https://www.npmjs.com/package/@elaraai/e3-core): Object store, dataflow orchestrator, execution state
  - [@elaraai/e3-types](https://www.npmjs.com/package/@elaraai/e3-types): Shared type definitions for e3 packages
  - [@elaraai/e3-cli](https://www.npmjs.com/package/@elaraai/e3-cli): `e3 repo`, `e3 package`, `e3 workspace`, `e3 start`, `e3 watch`, `e3 logs` commands
  - [@elaraai/e3-api-client](https://www.npmjs.com/package/@elaraai/e3-api-client): HTTP client for remote e3 repositories
  - [@elaraai/e3-api-server](https://www.npmjs.com/package/@elaraai/e3-api-server): REST API server for e3 repositories
  - [@elaraai/e3-api-tests](https://www.npmjs.com/package/@elaraai/e3-api-tests): Shared API compliance test suites

## Links

- **Website**: [https://elaraai.com/](https://elaraai.com/)
- **East Repository**: [https://github.com/elaraai/east-workspace/tree/main/libs/east](https://github.com/elaraai/east-workspace/tree/main/libs/east)
- **Issues**: [https://github.com/elaraai/east-workspace/issues](https://github.com/elaraai/east-workspace/issues)
- **Email**: support@elara.ai

## About Elara

East is developed by [Elara AI Pty Ltd](https://elaraai.com/), an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.

---

*Developed by [Elara AI Pty Ltd](https://elaraai.com/).*

---

*Developed by [Elara AI Pty Ltd](https://elaraai.com/)*
