Metadata-Version: 2.4
Name: mercure-publisher
Version: 0.1.0
Summary: Typed Python client to publish updates to a Mercure Hub, with Redis-backed JWT caching support
Project-URL: Homepage, https://github.com/not-empty/mercure-publisher-python
Project-URL: Issues, https://github.com/not-empty/mercure-publisher-python/issues
Author-email: Not Empty Foundation <dev@not-empty.org>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: httpx
Requires-Dist: pyjwt
Requires-Dist: redis
Provides-Extra: dev
Requires-Dist: fakeredis; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Description-Content-Type: text/markdown

# mercure-publisher

[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)

**mercure-publisher** is a typed Python client to publish updates to a
[Mercure Hub](https://mercure.rocks/), with Redis-backed caching of the
generated publisher JWT so it isn't re-created on every publish call.

Features:

- 🔐 Builds the publisher JWT (`mercure.publish` claim) from a typed config
- ⚡ Optional Redis cache for the JWT (checked before minting a new token)
- 🔁 Sync and async clients, both backed by `httpx`
- 🧩 `data` accepts a `dict` and serializes it to JSON for you (or pass a `str` for a raw payload)
- 📦 Fully typed with dataclasses and type hints

---

## Installation

```bash
pip install mercure-publisher
```

Requires a reachable Redis instance (used to cache the publisher JWT); pass
`redis_config=None` to disable caching without removing the dependency.

---

## Usage

### Configure

```python
from mercure_publisher import MercureConfig, RedisConfig

config = MercureConfig(
    hub_url="https://hub.example.com/.well-known/mercure",
    publisher_jwt_key="!ChangeThisMercureHubJWTSecretKey!",
    publish_topics=["https://example.com/books/{id}"],  # or ["*"] for any topic
    jwt_ttl_seconds=3600,
    redis_config=RedisConfig(
        host="localhost",
        port=6379,
        key_prefix="mercure_publisher:",
    ),
)
```

`redis_config=None` (the default) disables token caching — a new JWT is
generated on every publish.

### Publish (sync)

```python
from mercure_publisher import MercurePublisher

with MercurePublisher(config) as publisher:
    event_id = publisher.publish(
        topic="https://example.com/books/1",
        data={"status": "published"},
    )
```

### Publish (async)

```python
from mercure_publisher import AsyncMercurePublisher

async with AsyncMercurePublisher(config) as publisher:
    event_id = await publisher.publish(
        topic="https://example.com/books/1",
        data={"status": "published"},
    )
```

### Publishing to multiple topics / private updates

```python
publisher.publish(
    topic=["https://example.com/books/1", "https://example.com/authors/1"],
    data='{"status": "published"}',
    private=True,
    id="event-123",
    type="book.updated",
    retry=1000,
)
```

---

## License

MIT © [Not Empty](https://github.com/not-empty)

**Not Empty Foundation - Free codes, full minds**
