Metadata-Version: 2.4
Name: cymongoose
Version: 0.2.0
Summary: High-performance Python bindings for the Mongoose embedded networking library
Keywords: mongoose,networking,http,https,websocket,mqtt,server,client,embedded,async,high-performance,tls,ssl
Author-Email: Shakeeb Alireza <shakfu@users.noreply.github.com>
License-Expression: GPL-2.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: C
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/shakfu/cymongoose
Project-URL: Repository, https://github.com/shakfu/cymongoose
Project-URL: Documentation, https://shakfu.github.io/cymongoose/
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# cymongoose

Python bindings for the Mongoose embedded networking library, built with Cython.

## Overview

**cymongoose** provides Pythonic access to [Mongoose](https://github.com/cesanta/mongoose), a lightweight embedded networking library written in C. It supports HTTP servers, WebSocket, TCP/UDP sockets, and more through a clean, event-driven API.

**[Documentation](https://shakfu.github.io/cymongoose/)** | **[API Reference](https://shakfu.github.io/cymongoose/api/)** | **[Examples](https://shakfu.github.io/cymongoose/examples/)**

## Features

- **HTTP/HTTPS, WebSocket/WSS, MQTT/MQTTS** -- full protocol support with TLS
- **TCP/UDP, DNS, SNTP** -- raw sockets and network utilities
- **Timers** -- periodic callbacks with thread-safe cancellation
- **Event-driven** -- non-blocking I/O with a simple event loop
- **GIL-free** -- 24 methods release the GIL for true parallel execution
- **High performance** -- 60k+ req/sec (6-37x faster than pure Python frameworks)
- **Asyncio support** -- `AsyncManager` for asyncio integration
- **Type hints** -- full `.pyi` stubs and `py.typed` marker

## Installation

```sh
pip install cymongoose
```

From source:

```sh
git clone https://github.com/shakfu/cymongoose
cd cymongoose
make
```

Requires Python 3.10+, CMake 3.15+, Cython 3.0+, and a C compiler.

## Quick Start

```python
from cymongoose import Manager, MG_EV_HTTP_MSG

def handler(conn, event, data):
    if event == MG_EV_HTTP_MSG:
        conn.reply(200, "Hello, World!")

mgr = Manager(handler)
mgr.listen("http://127.0.0.1:8000")
mgr.run()
```

More examples:

```python
# Serve static files
def handler(conn, event, data):
    if event == MG_EV_HTTP_MSG:
        conn.serve_dir(data, root_dir="./public")

# WebSocket echo
from cymongoose import MG_EV_WS_MSG

def handler(conn, event, data):
    if event == MG_EV_HTTP_MSG:
        conn.ws_upgrade(data)
    elif event == MG_EV_WS_MSG:
        conn.ws_send(data.text)

# Per-listener handlers on different ports
mgr = Manager()
mgr.listen("http://127.0.0.1:8080", handler=api_handler)
mgr.listen("http://127.0.0.1:8090", handler=web_handler)
mgr.run()
```

See the [quickstart guide](https://shakfu.github.io/cymongoose/quickstart/) and [examples](https://shakfu.github.io/cymongoose/examples/) for more.

## Testing

```sh
make test           # Run all tests (366 tests)
make test-asan      # Run with AddressSanitizer (memory safety)
make qa             # Run tests + lint + type check + format
```

## Development

```sh
make build          # Rebuild the Cython extension
make clean          # Remove build artifacts
make docs-serve     # Serve documentation locally
make help           # Show all available targets
```

## License

Licensed under **GPL-2.0-or-later**, matching the [Mongoose C library](https://github.com/cesanta/mongoose) license. See [LICENSE](LICENSE) for details.

For proprietary use, a [commercial Mongoose license](https://mongoose.ws/licensing/) from Cesanta is required.

## Links

- [Documentation](https://shakfu.github.io/cymongoose/)
- [Mongoose Documentation](https://mongoose.ws/)
- [GitHub Repository](https://github.com/shakfu/cymongoose)
