Metadata-Version: 2.4
Name: py-asyncfiles
Version: 1.1.3
Summary: High-performance async file I/O library built on libuv
Home-page: https://github.com/cve-zh00/asyncfiles
Author: bastian garcia
Author-email: Bastián García <bastiang@uc.cl>
Maintainer-email: Bastián García <bastiang@uc.cl>
License: MIT
Keywords: async,asyncio,file,io,libuv,performance,cython
Platform: POSIX
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
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 :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: Cython~=3.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: platform
Dynamic: requires-python

# asyncfiles

[![Python Versions](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/cve-zh00/asyncfiles/issues)

**asyncfiles** is a high-performance async file I/O library for Python, built on top of [libuv](https://libuv.org/) using Cython. It provides true asynchronous file operations without blocking the event loop, offering significant performance improvements over thread-based alternatives.

## 🚀 Features

- **True Async I/O**: Built directly on libuv's async filesystem operations
- **High Performance**: Cython-optimized with zero-copy buffer operations
- **Non-blocking**: No thread pools - pure async I/O all the way down
- **Simple API**: Familiar async context manager interface
- **Type Hints**: Full typing support for better IDE integration
- **Memory Efficient**: Configurable buffer sizes for optimal memory usage

## 📦 Installation

### From PyPI

```bash
pip3 install py-asyncfiles
```

### Requirements

- Python 3.8 or higher
- Cython ~3.0
- A C compiler (gcc, clang, or MSVC)
- libuv (included as submodule)


## 🔥 Quick Start

```python
import asyncio
from asyncfiles import open

async def main():
    # Read a file
    async with open('example.txt', 'r') as f:
        content = await f.read()
        print(content)
    
    # Write to a file
    async with open('output.txt', 'w') as f:
        await f.write('Hello, async world!')

asyncio.run(main())
```

## 📖 Usage Examples

### Reading Files

```python
import asyncio
from asyncfiles import open

async def read_file():
    # Read entire file
    async with open('data.txt', 'r') as f:
        content = await f.read()
        return content

asyncio.run(read_file())
```

### Writing Files

```python
import asyncio
from asyncfiles import open

async def write_file():
    async with open('output.txt', 'w') as f:
        await f.write('Line 1\n')
        await f.write('Line 2\n')
        await f.write('Line 3\n')

asyncio.run(write_file())
```

### Custom Buffer Size

```python
import asyncio
from asyncfiles import open

async def large_file():
    # Use 1MB buffer for large files
    async with open('large_file.bin', 'r', buffer_size=1024*1024) as f:
        data = await f.read()
        return data

asyncio.run(large_file())
```

### Multiple Concurrent Operations

```python
import asyncio
from asyncfiles import open

async def process_files():
    # Read multiple files concurrently
    async def read_file(path):
        async with open(path, 'r') as f:
            return await f.read()
    
    results = await asyncio.gather(
        read_file('file1.txt'),
        read_file('file2.txt'),
        read_file('file3.txt'),
    )
    
    return results

asyncio.run(process_files())
```

## 🎯 Supported File Modes

| Mode | Description |
|------|-------------|
| `'r'` | Read text (default) |
| `'w'` | Write text (truncate) |
| `'a'` | Append text |
| `'x'` | Exclusive creation |
| `'r+'` | Read and write |
| `'w+'` | Write and read (truncate) |
| `'a+'` | Append and read |

Additional modifiers:
- `'b'`: Binary mode
- `'t'`: Text mode (default)

## ⚡ Performance

asyncfiles significantly outperforms thread-based async file libraries:

```
Benchmark Results (10MB file):
├── asyncfiles:    45.2 ms  ← 🏆 Fastest
├── aiofile:       78.4 ms
├── aiofiles:      112.6 ms
└── stdlib+thread: 156.3 ms
```

Run benchmarks yourself:

```bash
python -m benchmark.benchmark_read
python -m benchmark.benchmark_write
```


## 🛠️ Development

### Building from Source

```bash
# Clean build
make clean

# Compile with optimizations
make compile

# Debug build with line tracing
make debug

# Run tests
make test
```

### Running Tests

```bash
# Run all tests
make test

# Run with async debug mode
PYTHONASYNCIODEBUG=1 python -m unittest discover -v tests

# Test installed package
make testinstalled
```

### Code Style

- Follow PEP 8 for Python code
- Use type hints where applicable
- Add docstrings for public APIs
- Keep Cython code clean and well-commented

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

This project is heavily inspired by [uvloop](https://github.com/MagicStack/uvloop), which pioneered the use of libuv in Python's async ecosystem. The build system, Cython integration patterns, and overall architecture follow uvloop's excellent design.

Special thanks to:
- **uvloop** team for showing how to properly integrate libuv with Python
- **libuv** project for the excellent async I/O library
- **Cython** team for making high-performance Python extensions possible

## 🔗 Related Projects

- [uvloop](https://github.com/MagicStack/uvloop) - Ultra fast asyncio event loop
- [aiofiles](https://github.com/Tinche/aiofiles) - Thread-based async file I/O
- [aiofile](https://github.com/mosquito/aiofile) - Another async file library
- [libuv](https://github.com/libuv/libuv) - Cross-platform async I/O

## 📊 Status

**Current Status**: Experimental / In Development

This project is currently in active development. The API may change. Production use is not recommended yet.

### Roadmap
- [ ] Iteration support
- [X] Comprehensive test suite
- [ ] Complete documentation
- [x] Binary mode support
- [x] Seek/tell operations
- [ ] File metadata operations
- [ ] PyPI package release
- [ ] CI/CD pipeline
- [ ] Performance optimizations
- [ ] More comprehensive benchmarks

## 💬 Support

- **Issues**: [GitHub Issues](https://github.com/cve-zh00/asyncfiles/issues)

## 📈 Benchmarks

For detailed benchmark results and methodology, see [benchmark/README.md](benchmark/README.md).

---

**Made with ❤️ and ⚡ by Zh00**
