Metadata-Version: 2.4
Name: localpub
Version: 0.1.0
Summary: A decentralized, brokerless pub/sub for multi-process communication on a single machine
Project-URL: Homepage, https://github.com/irachex/localpub
Project-URL: Repository, https://github.com/irachex/localpub
Project-URL: Documentation, https://github.com/irachex/localpub/blob/main/docs/index.md
Project-URL: Issues, https://github.com/irachex/localpub/issues
Author: Huayi Zhang
License: MIT
License-File: LICENSE
Keywords: asyncio,brokerless,decentralized,ipc,message-bus,multi-process,pub-sub,pubsub
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
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: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# localpub 🥃

> A decentralized, brokerless pub/sub for multi-process communication on a single machine.
>
> *A local pub for your processes to hang out.* 🍻

[![CI](https://github.com/irachex/localpub/actions/workflows/ci.yml/badge.svg)](https://github.com/irachex/localpub/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

## Features

- **Multiple backends**: Choose the right transport for your workload:
  - **Unix Domain Socket Mesh** — peer-to-peer, no single point of failure
  - **Unix Domain Socket Broker** — competitive binding, first process becomes broker
  - **mmap Ring Buffer** — ultra-low-latency shared memory
- **Async-first**: Modern `asyncio` APIs with convenient sync wrappers
- **Pluggable serialization**: Pass any Python object; swap in JSON, msgpack, or your own
- **Zero external dependencies**: Pure stdlib for the core package
- **Fully typed**: PEP 561 compatible with strict type coverage

## Quick Start

```python
import asyncio
from localpub import UnixMeshBus

async def main():
    bus = UnixMeshBus("/tmp/mypub")
    await bus.open()

    await bus.subscribe("greetings", lambda env: print(f"Received: {env.payload}"))
    await bus.publish("greetings", {"msg": "hello from process A"})

    await asyncio.sleep(1)
    await bus.close()

asyncio.run(main())
```

### Synchronous API

```python
from localpub import UnixMeshBus, SyncBus

bus = SyncBus(UnixMeshBus("/tmp/mypub"))
with bus:
    bus.subscribe("greetings", lambda env: print(f"Received: {env.payload}"))
    bus.publish("greetings", "hello")
```

### Pick a backend

| Backend | Latency | Throughput | Brokerless | Use case |
|---------|---------|------------|------------|----------|
| `UnixMeshBus` | Low | Medium | Yes | Resilient, no single point of failure |
| `UnixBrokerBus` | Low | High | No (elected) | General purpose, simple topology |
| `MmapRingBus` | Ultra-low | Very High | Yes | High-throughput same-machine IPC |

## Installation

```bash
pip install localpub
```

## Development

```bash
# Install dependencies
make install

# Run tests
make test

# Lint & format
make lint
make format

# Type check
make typecheck

# Run all checks (lint + typecheck + test)
make check

# Build wheel and sdist
make build
```

## License

MIT — see [LICENSE](LICENSE).
