Skip to content

Update README.md #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MotherOfProgrammers merged 1 commit into from
Oct 7, 2026
Merged

Update README.md #9

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 31 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,15 @@

# Lithon

### Python-like syntax. Static types. Native x86-64 execution.
### Native execution for typed Python.

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square\&logo=github-actions)](https://github.com/Project-Lithon/lithon/actions)
[![C++ Standard](https://img.shields.io/badge/C%2B%2B-20-00599C?style=flat-square\&logo=c%2B%2B)](https://en.cppreference.com/w/cpp/20)
[![Architecture](https://img.shields.io/badge/arch-x86--64-red?style=flat-square)](https://en.wikipedia.org/wiki/X86-64)
[![Typing](https://img.shields.io/badge/typing-mandatory%20static-green?style=flat-square)](#-static-typing)
[![Typing](https://img.shields.io/badge/typing-extended%20static-green?style=flat-square)](#-static-typing)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

**Lithon is an experimental Python-native programming language and compiler
that brings mandatory static typing, native x86-64 execution, and explicit
low-level memory access to the Python ecosystem.**
**Lithon is an experimental Python library and native x86-64 JIT that brings extended static typing, native execution, and explicit low-level memory access to Python code.**

</div>

Expand All @@ -28,36 +26,27 @@ low-level memory access to the Python ecosystem.**

## 🚀 What is Lithon?

Lithon is a **Python-like, statically typed programming language implemented
as a Python package**, with a custom native execution engine written in C++20.
Lithon is a **Python library and native execution engine** that runs `.py`
source code using an extended **PEP-526-style static typing syntax**.

The goal is simple:
Lithon is designed to keep Python's familiar source-code model while giving
the compiler explicit type information that can be used for static verification,
native machine-code generation, and predictable execution.

> **Keep Python's expressive syntax while giving the programmer explicit
> control over types, memory representation, and native machine-code execution.**
Lithon is **not a separate programming language**. Python remains the source
language and `.py` remains the source format. Lithon extends the typing
information available to the compiler so that supported Python code can be
lowered to native x86-64 machine code.

Lithon does not attempt to be a drop-in replacement for Python. It deliberately
chooses a more constrained model in exchange for predictability and native
execution.

A Lithon program is statically verified before native execution. Values have
explicit, fixed-width types such as `int[8]`, `int[16]`, `int[32]`, `int[64]`,
`float[64]`, `bool`, and typed pointers such as `ptr[int[16]]`.
For example:

For code that cannot currently be proven safe for the native tier, Lithon can
fall back to its Tier-0 interpreter when using automatic execution.
```python
x: int[64] = 10
y: int[64] = 20

With `--strict`, Lithon refuses programs that cannot be compiled natively.
result: int[64] = x + y

```text
Python-like source
│
▼
Static type / flow verification
│
├── proven native-safe ──► x86-64 machine code ──► CPU
│
└── unsupported ─────────► Tier-0 interpreter
print(result)
```

### Current status
Expand All @@ -78,8 +67,9 @@ drop-in Python replacement.

Lithon is built around several principles:

* **Python-like syntax** — familiar syntax without requiring Python's dynamic
execution model.
* **Python source with extended PEP-526 typing** — Lithon works directly with
`.py` source while providing additional type information to the native
execution pipeline.
* **Mandatory static typing** — types are verified before execution.
* **Fixed-width values** — integer widths are explicit.
* **Native execution** — supported programs can execute as generated x86-64
Expand All @@ -89,7 +79,7 @@ Lithon is built around several principles:
* **Interpreter fallback** — unsupported native cases can still execute through
Tier-0 when using automatic mode.
* **Explicit unsafe memory access** — pointer variables require an `_` prefix.
* **Compiler refusal over silent miscompilation** — when Lithon cannot prove
* **JIT/Compiler refusal over silent miscompilation** — when Lithon cannot prove
something, the native tier refuses it.

The last point is fundamental to the project:
Expand Down Expand Up @@ -283,7 +273,7 @@ Lithon currently spans four implementation layers:

```mermaid
graph TD
A[Python-like Lithon Source] --> B[Frontend]
A[Python .py Source] --> B[Frontend]
B --> C[Typed IR]
C --> D[Static Flow Verification]

Expand Down Expand Up @@ -786,7 +776,7 @@ rather than hiding the fact that a variable contains a raw address.

| Feature | CPython | Cython / mypyc | PyPy | **Lithon** |
| :-------------------- | :------------------- | :-------------------------- | :------------- | :------------------------ |
| Syntax | Python | Python | Python | **Python with Extended PEP-526** |
| Syntax | Python | Python | Python | **Python `.py` + Extended PEP-526** |
| Primary execution | Bytecode interpreter | C extensions | Tracing JIT | **Native x86-64** |
| Static typing | No | Optional | No | **Mandatory** |
| Fixed-width integers | No | Possible | No | **Built-in** |
Expand All @@ -801,8 +791,9 @@ Lithon is not intended to replace Python's enormous ecosystem.

Instead, it explores a different point in the design space:

> **What if a Python-like language made static types, fixed-width values,
> native execution, and low-level memory access first-class features?**
> **What if Python code could retain its familiar source model while giving the
> execution engine explicit static types, fixed-width values, native execution,
> and controlled low-level memory access?**

---

Expand Down Expand Up @@ -892,8 +883,8 @@ than CPython, PyPy, Cython, Rust, or C++.

## 📍 Current Known Limitations

Lithon is powerful on its supported subset, but it is still an experimental
compiler.
Lithon is powerful on its supported subset, but its native execution engine is
still experimental.

Current limitations include:

Expand All @@ -907,7 +898,7 @@ Current limitations include:
* Some SSA/native paths remain opt-in or have known unsupported cases.
* There is no production AOT compiler yet.
* The PyPI package has **not yet received its stable public release**.
* The language is not intended to be a drop-in CPython replacement.
* Lithon is not intended to be a drop-in CPython replacement.

When the compiler cannot prove a construct is supported, it should refuse the
native tier rather than silently produce questionable machine code.
Expand Down Expand Up @@ -996,13 +987,11 @@ Lithon is entering its **community-preview stage**.

If you are interested in:

* programming-language design
* compiler construction
* JIT compilation
* x86-64 machine-code generation
* static analysis
* SSA and register allocation
* low-level Python-like languages
* systems programming

then feedback, experiments, bug reports, and technical criticism are welcome.
Expand All @@ -1017,6 +1006,6 @@ especially valuable.

Lithon is released under the [MIT License](LICENSE).

> **Python-like at the surface. Native at the core. Explicit by design.**
> **Native execution for typed Python. Explicit by design.**

</div>
Loading