Metadata-Version: 2.4
Name: splurge-pub-sub
Version: 2025.0.0
Summary: A lightweight pub-sub framework.
Author: Jim Schilling
Maintainer: Jim Schilling
License-Expression: MIT
Project-URL: Homepage, https://github.com/jim-schilling/splurge-pub-sub
Project-URL: Repository, https://github.com/jim-schilling/splurge-pub-sub
Project-URL: Documentation, https://github.com/jim-schilling/splurge-pub-sub#readme
Project-URL: Issues, https://github.com/jim-schilling/splurge-pub-sub/issues
Project-URL: Changelog, https://github.com/jim-schilling/splurge-pub-sub/blob/main/CHANGELOG.md
Keywords: splurge,pub-sub
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: hypothesis>=6.97.4; extra == "dev"
Requires-Dist: mypy>=1.18.2; extra == "dev"
Requires-Dist: pre-commit>=4.3.0; extra == "dev"
Requires-Dist: ruff>=0.12.7; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-cov>=6.2.1; extra == "test"
Requires-Dist: pytest-mock>=3.15.1; extra == "test"
Requires-Dist: hypothesis>=6.97.4; extra == "test"
Provides-Extra: lint
Requires-Dist: mypy>=1.18.2; extra == "lint"
Requires-Dist: ruff>=0.12.7; extra == "lint"
Dynamic: license-file

# splurge-pub-sub

[![PyPI version](https://badge.fury.io/py/splurge-pub-sub.svg)](https://pypi.org/project/splurge-pub-sub/)
[![Python versions](https://img.shields.io/pypi/pyversions/splurge-pub-sub.svg)](https://pypi.org/project/splurge-pub-sub/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

[![CI](https://github.com/jim-schilling/splurge-pub-sub/actions/workflows/ci-quick-test.yml/badge.svg)](https://github.com/jim-schilling/splurge-pub-sub/actions/workflows/ci-quick-test.yml)
[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](https://github.com/jim-schilling/splurge-pub-sub)
[![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)
[![mypy](https://img.shields.io/badge/mypy-checked-black)](https://mypy-lang.org/)

A lightweight, thread-safe publish-subscribe framework for Python applications. Splurge provides simple, Pythonic in-process event communication with full type safety and comprehensive error handling.

## Features

- **Lightweight**: Zero external dependencies, minimal footprint
- **Thread-Safe**: Full concurrency support with reentrant locks
- **Type-Safe**: Complete type annotations with mypy strict mode compliance
- **Simple API**: Subscribe, publish, unsubscribe with intuitive methods
- **Decorator Syntax**: `@bus.on("topic")` for simplified subscriptions
- **Topic Filtering**: Wildcard pattern matching for selective message delivery
- **Error Handling**: Custom error handlers for failed callbacks
- **Context Manager**: Automatic resource cleanup with `with` statement
- **95% Coverage**: Comprehensive test coverage across all features

## Quick Start

### Installation

```bash
pip install splurge-pub-sub
```

### Basic Usage

```python
from splurge_pub_sub import PubSub, Message

# Create a pub-sub bus
bus = PubSub()

# Subscribe to a topic
def handle_event(msg: Message) -> None:
    print(f"Received: {msg.data}")

sub_id = bus.subscribe("user.created", handle_event)

# Publish a message
bus.publish("user.created", {"id": 123, "name": "Alice"})
# Output: Received: {'id': 123, 'name': 'Alice'}

# Unsubscribe when done
bus.unsubscribe("user.created", sub_id)
```

### Decorator API

```python
@bus.on("user.updated")
def handle_user_updated(msg: Message) -> None:
    print(f"User updated: {msg.data}")

bus.publish("user.updated", {"id": 123, "status": "active"})
```

### Topic Filtering

```python
from splurge_pub_sub import TopicPattern

# Create patterns with wildcards
pattern = TopicPattern("user.*")
pattern.matches("user.created")  # True
pattern.matches("user.updated")  # True
pattern.matches("order.created")  # False

# Patterns with ? for single character
pattern = TopicPattern("user.?.created")
pattern.matches("user.a.created")  # True
pattern.matches("user.ab.created")  # False
```

### Error Handling

```python
def my_error_handler(exc: Exception, topic: str) -> None:
    print(f"Error on topic '{topic}': {exc}")

bus = PubSub(error_handler=my_error_handler)

@bus.on("risky.operation")
def handle_event(msg: Message) -> None:
    raise ValueError("Something went wrong!")

bus.publish("risky.operation", {})  # Error handler called
# Output: Error on topic 'risky.operation': Something went wrong!
```

### Context Manager

```python
with PubSub() as bus:
    bus.subscribe("topic", callback)
    bus.publish("topic", data)
    # Cleanup happens automatically
```

## Documentation

- **[README-DETAILS.md](docs/README-DETAILS.md)** - Comprehensive developer's guide with features, examples, and API overview
- **[API-REFERENCE.md](docs/api/API-REFERENCE.md)** - Complete API reference with all classes, methods, and error types
- **[CLI-REFERENCE.md](docs/cli/CLI-REFERENCE.md)** - Command-line interface documentation
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes

## Requirements

- Python 3.10 or later
- No external dependencies

## License

MIT License - see [LICENSE](LICENSE) file for details

## Author

Jim Schilling

## Support

For issues, questions, or contributions, visit the [GitHub repository](https://github.com/jim-schilling/splurge-pub-sub).
