Metadata-Version: 2.4
Name: talyn
Version: 0.6.3
Summary: Talyn: A robust, stable, and realistically fast Zig-powered event loop for Python's asyncio.
Author-email: Chaiwat Suttipongsakul <cwt@bashell.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cwt/talyn
Project-URL: Repository, https://github.com/cwt/talyn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.md
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Requires-Dist: mypy; extra == "lint"
Provides-Extra: benchmark
Requires-Dist: uvloop; extra == "benchmark"
Requires-Dist: prettytable; extra == "benchmark"
Requires-Dist: matplotlib; extra == "benchmark"
Requires-Dist: pillow; extra == "benchmark"
Dynamic: license-file

# Talyn: Robust, Stable AsyncIO Event Loop for Python

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
[![Python Compatibility](https://img.shields.io/badge/python-3.13%20%7C%203.14%20%7C%20Free--Threaded-blue.svg)](#-requirements)
[![Linux Compatibility](https://img.shields.io/badge/linux-7.0+%20%7C%20Fedora%2043--44-orange.svg)](#-requirements)
[![Zig Compatibility](https://img.shields.io/badge/zig-0.16.0-red.svg)](#-requirements)
[![PyPI Version](https://img.shields.io/pypi/v/talyn.svg)](https://pypi.org/project/talyn/)

**Talyn** is a robust, exceptionally stable, and realistically fast `asyncio` event loop drop-in replacement for Python, powered by the asynchronous capabilities of **Zig** and **io_uring**.

Talyn prioritizes **correctness, complete system safety, and high usability** over artificial micro-benchmark superiority. It is fully compatible with CPython's standard single-threaded and free-threaded (GIL-disabled) runtimes.

---

## 🚀 Features

- **Realistic Speed**: Designed to deliver solid and reliable I/O performance on Linux by leveraging `io_uring`'s native kernel-side asynchronous completion queues.
- **Robust & Crash-Resistant**: Meticulously hardened against circular reference memory leaks, stack alignment faults, signal interrupt deadlocks, and use-after-free bugs.
- **Full Asyncio Compatibility**: Passes 100% of standard Python `asyncio`, `subprocess`, `transports`, and connection-lifecycle test suites.
- **Modern Packaging**: Fully migrated to PEP 517/518 standard declarative `pyproject.toml` configuration.
- **GIL-Disabled Free-Threading Ready**: Fully compatible with `python3.13t` and `python3.14t` without memory races.

---

## 📜 Requirements

- **Python**: `>= 3.13` (Tested and verified under CPython `3.13`, `3.14`, `3.13t` (free-threaded), and `3.14t` (free-threaded))
- **Linux Kernel**: `>= 7.0` (Verified on Linux Kernel `7.0.x`)
- **Zig Compiler** (for source builds): `0.16.0` (Fedora packages)

> [!NOTE]
> **Tested Platform Verification**:
> Talyn has been built, compiled, and verified extensively under **Fedora 43-44** on an **x86_64** architecture equipped with an **Intel(R) Core(TM) Ultra 7 265** processor. Compatibility with other Linux distributions, older kernels, or alternative hardware architectures (e.g. AArch64) has not been verified yet. We welcome feedback and pull requests for other environments!

---

## 🔧 Installation

To compile and install Talyn locally, run:

```bash
pip install -e .
```

### ⚡ Optimization & Target Compilation (For Developers & Power Users)

By default, the pre-built wheels generated by `build.sh` are compiled targeting a **generic `x86_64`** CPU architecture baseline to ensure 100% universal compatibility across all 64-bit modern x86 Linux processors (e.g., matching standard PyPI `manylinux` wheel compatibility). 

Based on our benchmarks and comprehensive validation—including 100% passing results in the standard `asyncio` test suite across four distinct Python versions—**we publish the official binary packages (wheels) compiled in Starburst mode (Zig built with `ReleaseFast`)** to deliver peak performance out of the box with proven stability.

If you are compiling from source, you can customize the compilation optimize mode and target CPU architecture to unleash maximum performance:

#### 1. Compile and Optimize for your Native CPU (Highly Recommended)
To compile Talyn so that it takes full advantage of your host's exact CPU instructions (such as AVX2, AVX-512, cache alignment, etc.):
```bash
# Omit TALYN_CPU so Zig defaults to native CPU optimization
TALYN_OPTIMIZE=ReleaseFast pip install .
```

#### 2. Configure Compilation Modes
You can control Zig's optimize mode by setting the `TALYN_OPTIMIZE` environment variable (defaults to `Debug` for developer convenience):
* `TALYN_OPTIMIZE=Debug` (Default): Compiles with heavy runtime assertions and debug symbols.
* `TALYN_OPTIMIZE=ReleaseSafe`: Compiles with full optimizations but keeps safety checks (e.g. out-of-bounds, overflows).
* `TALYN_OPTIMIZE=ReleaseFast`: Compiles with maximum optimizations (Starburst mode), disabling safety checks for peak execution speed.

#### 3. Target a Specific CPU microarchitecture
You can force Zig to compile for a specific target CPU microarchitecture (like `x86_64_v2` or `x86_64_v3`):
```bash
TALYN_OPTIMIZE=ReleaseFast TALYN_CPU=x86_64_v3 pip install .
```

---

## 📦 Basic Usage

```python
import talyn
import asyncio

async def main():
    print("Hello from Talyn!")
    await asyncio.sleep(1)
    print("Goodbye from Talyn!")

# Run using Talyn event loop
talyn.run(main())
```

---

## 💝 Historical Credits & Origin

Talyn is spun off from **[Leviathan](https://github.com/kython28/leviathan)**, an event loop originally pioneered by **[Enrique Mora](https://github.com/kython28)**. Enrique Mora's creative spark and vision of merging Zig, `io_uring`, and `asyncio` laid the critical foundation and architecture of this project.

As Talyn evolved, the implementation underwent a complete systems-level refactoring to transition from a theoretical prototype to a production-grade, crash-resistant runtime:

- Eliminated multi-crossing Zig/Python vectorcall overhead by implementing a native C step trampoline.
- Redesigned completion handlers into flat, GC-safe ring buffers.
- Fully audited and resolved all memory-leak reference cycles under concurrent connections.

To honor the project's roots and Enrique's early work:

- The original Leviathan README can be viewed at: [docs/historical/leviathan-readme.md](docs/historical/leviathan-readme.md)
- The original preliminary benchmarks can be viewed at: [docs/historical/leviathan-benchmark.md](docs/historical/leviathan-benchmark.md)

---

## 📖 Project Story

- **[Development Journey](docs/development-journey.md)** — The full story: from discovery to challenges, the shift from "ultra-fast" to "realistic fast and stable", and how Talyn was built.
- **[Why Talyn?](docs/talyn-naming.md)** — The personal story and meaning behind the new name.

---

## 📄 License

This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
