Metadata-Version: 2.4
Name: pulse-broker
Version: 0.0.2
Summary: Python SDK for Pulse Broker
Home-page: https://github.com/marcosrosa/pulse
Author: Marcos Rosa
Author-email: marcos@example.com
Project-URL: Bug Tracker, https://github.com/marcosrosa/pulse/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: grpcio>=1.50.0
Requires-Dist: protobuf>=4.21.0
Requires-Dist: pyyaml>=6.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Pulse Python SDK

Official Python client for [Pulse Broker](https://github.com/marcosrosa/pulse).

## Installation

```bash
pip install pulse-broker
```

## Configuration

The SDK looks for a `pulse.yaml` (or `pulse.yml`) file in your project root. If not found, it defaults to `localhost:5555` (HTTP) and `localhost:5556` (gRPC).

### Example `pulse.yaml`

```yaml
# Connection Settings
broker:
  host: "localhost"
  http_port: 5555
  grpc_port: 5556
  timeout_ms: 5000

# Client Defaults
client:
  id: "my-python-app"
  auto_commit: true       # Automatically commit offsets after successful processing
  max_retries: 3

# Topic Configuration
topics:
  - name: "events"
    create_if_missing: true
    config:
      fifo: false
      retention_bytes: 1073741824  # 1GB
    consume:
      auto_commit: true

  - name: "transactions"
    create_if_missing: true
    config:
      fifo: true
    consume:
      auto_commit: false  # Manual commit required
```

## Usage

### Producer

You can send dictionaries (automatically serialized to JSON) or raw bytes.

```python
from pulse import Producer

# Initialize (uses pulse.yaml or defaults)
# You can override settings: Producer(host="10.0.0.1", port=9090)
producer = Producer()

# Send JSON
producer.send("events", {"type": "user_created", "id": 123})

# Send Bytes
producer.send("logs", b"raw log line")

producer.close()
```

### Consumer

Use the `@consumer` decorator to register message handlers.

```python
from pulse import consumer, commit, run

# Simple Consumer (uses auto_commit from config)
@consumer("events")
def handle_event(msg):
    print(f"Received event: {msg.payload}")
    # msg.payload is a dict if JSON, else bytes

# Manual Commit Consumer
# Override config params directly in the decorator if needed
@consumer("transactions", auto_commit=False)
def handle_transaction(msg):
    try:
        process_payment(msg.payload)
        commit()  # Manually commit offset
        print(f"Processed transaction {msg.offset}")
    except Exception as e:
        print(f"Failed to process: {e}")
        # Do not commit, message will be redelivered on restart/rebalance

if __name__ == "__main__":
    print("Starting consumers...")
    run()  # Blocks and runs all registered consumers
```

## Development

1. Clone the repository.
2. Navigate to `sdk/python`.
3. Create a virtual environment:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   ```
4. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
5. Run tests:
   ```bash
   pytest
   ```

## Publishing to PyPI

1. Build the package:
   ```bash
   python3 setup.py sdist bdist_wheel
   ```
2. Upload to PyPI:
   ```bash
   twine upload dist/*
   ```
