Metadata-Version: 2.1
Name: tesselite-pubsub
Version: 0.1.5
Summary: general sugarcoat for all pubsub flavors.
License: MIT
Author: Marcel Ndeffo
Author-email: marcel.nasser@live.fr
Requires-Python: >=3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: google-cloud-pubsub (>=2.26.1,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: redis (>=5.1.1,<6.0.0)
Requires-Dist: retry (>=0.9.2,<0.10.0)
Description-Content-Type: text/markdown

# tesselite-pubsub
general sugarcoat for all pubsub flavors.

## pubsub
Publish Subscribe is a pretty simple mechanism understandable by any human. 

For example, it is the ruling mechanism of all Social Networks. 

But, yet very complex to code in Python given the variety of backends logic (redis, rabbitMQ, kafka, GCP PubSub, Azure Event Hubs..)

The goal of this library is to streamline the coding of Pubsub in two simple calls:

---
## usage

Available Brokers:

| internal name | official name       | client library                  |
|---------------|---------------------|---------------------------------|
| gcp-pubsub    | Goggle Cloud Pubsub | google-cloud-pubsub = "^2.26.1" |
| redis         | Redis               | redis = "^5.1.1"                |


### low level usage

*consume*

````python
from tesselite.pubsub import pubsubFactory

def callback(message): # callback function inputs serialized message 
    print(f"received this: {message}")
    
# consume loop
with pubsubFactory(broker="gcp-pubsub")(topic="tesselite-pubsub", log_name="consumer") as pubsub:
    pubsub.consume(callback=callback, deadLetter=None, subscription="tesselite")

````

*publish*


````python
from tesselite.pubsub import pubsubFactory

def encoder(): # callback function inputs serialized message 
    yield "hello world"
    
# publish loop
with pubsubFactory(broker="gcp-pubsub")(topic="tesselite-pubsub", log_name="publisher") as pubsub:
    for msg in encoder():
        pubsub.publish(msg)

````


### high level usage

*consume*

````python
from tesselite.samples import consume # importing consume sample


def callback(message): # callback function inputs serialized message 
    print(f"received this: {message}")

if __name__ == '__main__':
    consume(broker='gcp-pubsub', callback=callback) # single-lined consume loop (default topic: tesselite-pubsub
````

*publish*

````python
from tesselite.samples import consume # importing consume sample


def callback(message): # callback function inputs serialized message 
    print(f"received this: {message}")

if __name__ == '__main__':
    consume(broker='gcp-pubsub', callback=callback) # single-lined consume loop (default topic: tesselite-pubsub
````

---

## Behavior

### Best Case Scenario

The interface to all broker backends technology is generic. One would swap seamlessly to any broker technology:

````python
from tesselite import pubsubFactory

# broker : gcp-pubsub
client_gcp = pubsubFactory(broker="gcp-pubsub")(topic="tesselite-pubsub", log_name="tesselite")

# broker : redis
client_redis = pubsubFactory(broker="redis")(topic="tesselite-pubsub", log_name="tesselite")
````

The connection to broker auto-heals when the broker backend is unavailable.

The generic mechanics bellow works for all broker backends:
1. topic checkout
2. topic creation
3. subscription checkout
4. subscription creation
5. publish or consume


### Pathologic Behaviors

A) 
Messages are lost if the subscription doesn't exist →
This is an incurable limitation of pubsub mechanics. 

B) 
The broker `redis` would drop messages if the consumer disconnects →
This seems to be related to 'livestream' behavior of Redis.

C)
The broker `gcp-pubsub` would freeze for a random timeperiod if no messages are available →
This would generate sluggishness from time to time.

Therefore, the broker `redis` is ideal for livestreaming but not for message retention critical PaaS.

Therefore, the broker `gcp-pubsub` is ideal for message retention critical PaaS but maybe sluggish for livestream.

