Metadata-Version: 2.4
Name: go-astty
Version: 0.3.7
Summary: go-astty is modular process orchestration gate for seamless synchronous and asynchronous command-line executions in Python.
Project-URL: Codeberg, https://codeberg.org/Fyllus/go-astty
Project-URL: Github, https://github.com/Fyllus/go-astty
Author-email: Fyllus <Fyllus@git.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: pygit2>=1.14.0
Description-Content-Type: text/markdown

# Go-astty

Version: `0.3.7` : Optimized performance by eliminating redundancies and improving vital components.

`go-astty` (Gate of Asynchronous and Synchronous TTY) is a minimalist, ultra-high-performance process orchestration layer for seamless synchronous and asynchronous command-line executions in Python.

By bypassing heavy high-level abstractions, it maps directly to native subsystem layers for Windows NT (`_winapi`) and POSIX (`posix_spawn`), matching the performance of CPython's native `subprocess` while providing decoupled, data-driven pipelines.

---

## Performance-Driven Architecture

The framework is stripped of runtime bloat to achieve near-zero execution overhead through critical low-level optimizations:

* **Fast Process Spawning (`posix_spawn`)**: Bypasses the costly overhead of `os.fork()` on POSIX layers. By using native `posix_spawn` primitives, it completely skips the interpreter's thread-lock/GIL and memory page tables duplication, reducing process creation time from **~2.7 ms down to ~1.04 ms** (matching native C performance). For implementation details, see [docs/UNIFIED.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/docs/UNIFIED.md).
* **Memory-Optimized Lifecycle (`__slots__`)**: Core tracking objects discard dynamic instance dictionaries (`__dict__`). Lifecycles are bound directly to fixed memory structures, optimizing allocation inside hot execution loops. For structural details, see [docs/TYPES.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/docs/TYPES.md).
* **Non-Blocking Deadlock Prevention**: Asynchronous pipelines run stream buffer consumption and process termination tracking concurrently via `asyncio.gather`, eliminating pipeline blockages caused by full OS pipe limits. For API details, see [docs/ASTTY.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/docs/ASTTY.md).

---

## Technical Documentation Breakdown

For detailed architectural breakdowns, internal variables, and low-level subsystem mapping, consult the specialized documentation modules:

* [docs/ASTTY.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/ASTTY.md) – **Core API Reference**: Full breakdown of the Pure Functional Pipeline (`exec_sync`/`exec_async`) and Object-Oriented Pipeline (`SyncExecution`/`AsyncExecution`).
* [docs/TYPES.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/TYPES.md) – **Memory Type & Vector Reference**: Implementation details of high-performance memory structures (`UnifiedHandle`, `UnifiedIOBuffer`, `UnifiedTask`, `UnifiedGateway`).
* [docs/UNIFIED.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/UNIFIED.md) – **Low-Level Subsystem Abstraction**: Cross-platform abstractions normalizing Windows NT Win32 API calls and POSIX native syscall routines.
* [docs/EXECUTION.md](https://codeberg.org/Fyllus/go-astty/src/branch/main/docs/EXECUTION.md) – **State & Lifecycle Orchestration**: Pre-flight setups, pipe allocation algorithms, and process image spawning lifecycles (`init_startup`/`post_startup`).

---

## Install from repository

```bash
git clone https://github.com/fyllus/go-astty.git
```

or

```bash
git clone https://codeberg.org/Fyllus/go-astty.git
```

```bash
cd go-astty
pip install .
```

## Install from pip

```bash
python -m pip install go-astty
```

---

## Quick Start Usage

### 1. Pure Functional Pipeline

Lightweight, stateless functional gateways for immediate execution and fast resource cleanup.

```python
import asyncio
from goastty.astty import exec_sync, exec_async

# Synchronous Sequential Pipeline
status_sync, output = exec_sync("tar", ["-czf", "backup.tar.gz", "src/"])

# Asynchronous Concurrent Pipeline
status_async, output = await exec_async("ping", ["-c", "3", "google.com"])

```

### 2. Object-Oriented Pipeline

Stateful, data-driven context managers engineered for complex orchestration workflows.

```python
import asyncio
from goastty.types import SyncTask, AsyncTask
from goastty.astty import SyncExecution, AsyncExecution

# Synchronous OO Pipeline
task_sync = SyncTask("git", "status")
status_sync = SyncExecution(task_sync).run(get_stderr=True)

# Asynchronous OO Pipeline

task_async = AsyncTask("ls", "-la") 
status_async = await AsyncExecution(task_async).run(get_stderr=False)

# task.stdout and .stderr to get outputs, or, task.data to acess main data structure

```
