Metadata-Version: 2.4
Name: kycli
Version: 0.1.3
Summary: **kycli** is a high-performance Python CLI toolkit built with Cython for speed.
Author: Balakrishna Maduru
Author-email: balakrishnamaduru@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Cython
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-python
Dynamic: summary

# 🔑 kycli — High-Performance Key-Value Toolkit

`kycli` is a lightweight, blazing-fast key-value storage engine built with **Cython** and linked directly against the **Raw SQLite C API (`libsqlite3`)**. It offers both a robust Command Line Interface (CLI) for terminal productivity and a high-performance, asynchronous Python library API.

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## ⚡ Performance: Redefining "Fast"

By removing the Python `sqlite3` wrapper and using direct C-level interactions, `kycli` achieves microsecond-level latency that rivals in-memory stores like Redis.

| Operation | Implementation | Avg Latency | Comparison |
| :--- | :--- | :--- | :--- |
| **Get Key** | **Direct C API** | **0.0028 ms** (2.8 µs) | **150x faster** than standard Python wrappers |
| **Get Key** | **Async (Threadpool)** | 0.0432 ms | Ideal for high-throughput backends |
| **Save Key** | **Atomic Sync** | 0.1895 ms | Durable Disk I/O |

---

## 🚀 Quick Start

### Installation
```bash
pip install kycli
```

### Basic Terminal Flow
```bash
# Save a secret
kys my_api_key "sk-proj-12345"

# Retrieve it (Microsecond speed)
kyg my_api_key

# List everything with Regex support
kyl "api_.*"
```

---

## 💻 CLI Usage

The CLI is designed to be intuitive and safe, featuring **overwrite protection** and **atomic operations**.

| Command | Action | Example |
| :--- | :--- | :--- |
| `kys` | **Save** a value | `kys username "balu"` |
| `kyg` | **Get** a value (supports Regex) | `kyg "user.*"` |
| `kyl` | **List** keys (supports Regex) | `kyl "prod_.*"` |
| `kyv` | **View** history/audit logs | `kyv username` |
| `kyd` | **Delete** a key | `kyd old_token` |
| `kye` | **Export** data (CSV/JSON) | `kye data.json json` |
| `kyi` | **Import** data | `kyi backup.csv` |

---

## 🐍 Python Library API

### Synchronous (High-Speed)
```python
from kycli import Kycore

with Kycore() as core:
    # Set and Get (Dict-style)
    core['app:mode'] = 'production'
    print(core['app:mode'])  # 2.8 µs retrieval
```

### Asynchronous (High-Throughput)
Perfect for FastAPI, Sanic, or any `asyncio` based application.
```python
import asyncio
from kycli import Kycore

async def main():
    with Kycore() as core:
        # Non-blocking async operations
        await core.save_async('session:id', 'xyz789')
        val = await core.getkey_async('session:id')
        print(f"Fetched: {val}")

asyncio.run(main())
```

---

## 🛡️ Key Features
- **Raw C Integration**: Direct binding to `libsqlite3` for zero abstraction overhead.
- **Asynchronous I/O**: Offloaded database tasks using thread-pools for non-blocking execution.
- **Audit Logging**: Full history of key-value changes kept in an indexed `audit_log` table.
- **Overwrite Protection**: Interactive (Y/N) confirmation prevents accidental data loss.
- **Atomic Operations**: Exports and imports use temporary staging to prevent file corruption.

---

## 🛠 Architecture

- **Engine**: SQLite 3 (WAL Mode enabled for high concurrency).
- **Core**: Compiled via Cython to machine code.
- **Security**: Keys are lowercased and stripped automatically to maintain data integrity.

---

## 👤 Author

**Balakrishna Maduru**  
- [GitHub](https://github.com/balakrishna-maduru)  
- [LinkedIn](https://www.linkedin.com/in/balakrishna-maduru)  
- [Twitter](https://x.com/krishonlyyou)

---
*Optimized for Performance by Antigravity*
