Metadata-Version: 2.4
Name: spindlex
Version: 0.6.9
Summary: A modern, high-performance SSHv2 and SFTP client/server library
Author: Stratza Labs
Author-email: David Azani <david@stratza.com>, Adi Roth <adi@stratza.com>
Maintainer: Stratza Labs
Maintainer-email: David Azani <david@stratza.com>, Adi Roth <adi@stratza.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/stratza/spindlex
Project-URL: Documentation, https://spindlex.readthedocs.io/
Project-URL: Repository, https://github.com/stratza/spindlex
Project-URL: Issues, https://github.com/stratza/spindlex/issues
Project-URL: Changelog, https://github.com/stratza/spindlex/blob/main/docs/changelog.md
Keywords: ssh,sftp,client,server,cryptography,security,automation,devops,asyncio,high-performance,remote-execution,file-transfer,modern-ssh,secure-shell
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=46.0.7
Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
Provides-Extra: gssapi
Requires-Dist: gssapi>=1.8.0; sys_platform != "win32" and extra == "gssapi"
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-xdist>=2.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.5; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: safety>=2.3.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: pytest-docker>=2.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.1.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.22.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.6.0; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.16.1; extra == "docs"
Requires-Dist: pygments>=2.20.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-xdist>=2.0; extra == "test"
Requires-Dist: pytest-timeout>=2.0.0; extra == "test"
Requires-Dist: coverage>=6.0; extra == "test"
Dynamic: license-file

<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&amp;color=gradient&amp;customColorList=18,18,18,48,25,52,18,18,18&amp;height=200&amp;section=header&amp;text=SpindleX&amp;fontSize=80&amp;fontColor=bb86fc&amp;fontAlignY=45&amp;desc=High-Performance%20SSH%20and%20SFTP%20for%20Python&amp;descSize=22&amp;descColor=b39ddb&amp;descAlignY=70&amp;animation=fadeIn" width="100%" />

<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=24&duration=3000&pause=1000&color=bb86fc&center=true&vCenter=true&width=600&lines=High-Performance+SSHv2+%E2%9A%A1;Native+AsyncIO+Support+%F0%9F%8C%91;Recursive+SFTP+Automation+%F0%9F%94%84;Secure+by+Default+%E2%9A%99%EF%B8%8F" alt="Typing SVG" />

<br/>

[![PR Gate](https://img.shields.io/github/actions/workflow/status/stratza/spindlex/ci-pr.yml?branch=main&style=for-the-badge&logo=github&label=PR%20Gate&labelColor=1a1a1a)](https://github.com/stratza/spindlex/actions/workflows/ci-pr.yml)
[![Compatibility](https://img.shields.io/github/actions/workflow/status/stratza/spindlex/ci-matrix.yml?branch=main&style=for-the-badge&logo=github&label=Compatibility&labelColor=1a1a1a)](https://github.com/stratza/spindlex/actions/workflows/ci-matrix.yml)
[![Security](https://img.shields.io/github/actions/workflow/status/stratza/spindlex/security.yml?branch=main&style=for-the-badge&logo=github&label=Security&labelColor=1a1a1a)](https://github.com/stratza/spindlex/actions/workflows/security.yml)
[![Coverage](https://img.shields.io/codecov/c/github/stratza/spindlex?style=for-the-badge&logo=codecov&labelColor=1a1a1a)](https://codecov.io/gh/stratza/spindlex)
[![PyPI Version](https://img.shields.io/pypi/v/spindlex?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a1a)](https://pypi.org/project/spindlex/)
[![License](https://img.shields.io/pypi/l/spindlex?style=for-the-badge&color=bb86fc&labelColor=1a1a1a)](https://github.com/stratza/spindlex/blob/main/LICENSE)

<br />

<a href="#-quick-start"><b><font color="#bb86fc">Quick Start</font></b></a> • <a href="https://spindlex.readthedocs.io/"><b><font color="#bb86fc">Documentation</font></b></a> • <a href="meta/SECURITY.md"><b><font color="#bb86fc">Security</font></b></a> • <a href="meta/CONTRIBUTING.md"><b><font color="#bb86fc">Contributing</font></b></a>

</div>

---

## ⚡ Overview

**SpindleX** is a modern SSH protocol implementation for Python 3.9+. It is designed for high-performance automation and secure file transfers, providing a clean alternative to legacy SSH libraries.

> [!WARNING]
> **Beta software.** The 0.6.x line is stabilising the core protocol, transport, and SFTP layers. Review [meta/SECURITY.md](meta/SECURITY.md) before deploying in production-facing workflows, pin exact versions, and audit your host key policy.

### 🔥 Key Features

- 🚀 **High Performance**: Optimized internal buffering (32KB chunks) for high-throughput SFTP and command execution.
- 🔄 **Native Async**: First-class `asyncio` support via `AsyncSSHClient` and `AsyncSFTPClient`.
- 🛡️ **Security**: Prioritizes modern primitives (Ed25519, AES-256-CTR) and disables legacy/weak ciphers.
- 🔗 **Advanced Tunneling**: Support for **ProxyJump** (bastion hosts) and TCP port forwarding.
- 📂 **Recursive SFTP**: Native support for recursive directory uploads and downloads.
- 🏷️ **Fully Typed**: Comprehensive type hints for IDE integration and static analysis.

---

## 💎 Why SpindleX?

- 💼 **Business Friendly**: MIT Licensed. Permissive use for commercial and proprietary projects.
- 📖 **Maintainable Code**: Modular architecture designed for clarity and easier security auditing.
- 🛠️ **Modern API**: Clean, intuitive interface with consistent error handling and minimal dependencies.
- 🧊 **Focused Scope**: No support for insecure legacy protocols, resulting in a leaner and more secure codebase.

---

## 🛠️ Tech Stack

<div align="left">

**Core Logic** ![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)
![Cryptography](https://img.shields.io/badge/Cryptography-FFD43B?style=flat-square&logo=python&logoColor=3776AB)

**Protocol** ![SSH](https://img.shields.io/badge/SSH-000000?style=flat-square&logo=ssh&logoColor=white)
![SFTP](https://img.shields.io/badge/SFTP-444444?style=flat-square&logo=files&logoColor=white)

**Concurrency** ![Asyncio](https://img.shields.io/badge/Asyncio-3776AB?style=flat-square&logo=python&logoColor=white)

</div>

---

## 🚀 Quick Start

### Installation

```bash
# Using pip
pip install spindlex

# Using uv
uv pip install spindlex
```

### 💻 Usage Preview

<details>
<summary><b>Synchronous Example</b></summary>

```python
from spindlex import SSHClient

with SSHClient() as client:
    client.get_host_keys().load()
    client.connect('example.com', username='admin')

    stdin, stdout, stderr = client.exec_command('uptime')
    print(f"Server Status: {stdout.read().decode().strip()}")
```
</details>

<details>
<summary><b>Asynchronous Example</b></summary>

```python
import asyncio
from spindlex import AsyncSSHClient

async def main():
    async with AsyncSSHClient() as client:
        await client.connect('example.com', username='admin')
        stdin, stdout, stderr = await client.exec_command('df -h')
        print(await stdout.read())

asyncio.run(main())
```
</details>

---

## 📊 Performance Benchmarks

SpindleX is optimized for high-throughput environments, significantly reducing protocol overhead compared to standard implementations.

| Operation | SpindleX | Legacy Libraries | Improvement |
|:---|:---:|:---:|:---:|
| **Handshake** | 0.32s | 0.85s | **~2.6x** |
| **Bulk SFTP** | 45 MB/s | 18 MB/s | **~2.5x** |
| **Overhead** | Low | High | 🔥 |

> [!TIP]
> Run the benchmark suite on your own hardware:  
> `python scripts/benchmark_compare.py`

---

## 🛡️ Security

- **Verification Enforced**: Host key verification is mandatory by default.
- **Log Sanitization**: Credentials and sensitive data are automatically filtered from logs.
- **Modern Defaults**: Ed25519 and ECDSA preferred for key exchange.
- **Full Policy**: See [meta/SECURITY.md](meta/SECURITY.md) for vulnerability reporting and security standards.

---

## 🤝 Contributing

Contributions are welcome. See `meta/CONTRIBUTING.md` for guidelines.

Distributed under the **MIT License**. See `LICENSE` for more information.

<div align="center">

---

*SpindleX Project © 2026 Stratza Labs*

</div>
