diff --git a/README.md b/README.md index 5e77550..f620232 100644 --- a/README.md +++ b/README.md @@ -41,15 +41,16 @@ There is a easy demo to show how to use broadcast-service. ```python from broadcast_service import broadcast_service + # callback of common method def handle_msg(params): - print(params) + print(f"handle_msg receive params: {params}") # callback of decorator @broadcast_service.on_listen(['my_topic']) def handle_decorator_msg(params): - print(params) + print(f"handle_decorator_msg receive params: {params}") if __name__ == '__main__': info = 'This is very important msg' @@ -59,7 +60,6 @@ if __name__ == '__main__': # publish broadcast broadcast_service.publish('my_topic', info) - ``` - You can use `publish, emit, broadcast` to send your topic msg and use `listen, on, subscribe` to listen your topic msg. diff --git a/docs/README.md b/docs/README.md index cb5df3f..5d02175 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,15 +38,16 @@ There is a easy demo to show how to use broadcast-service. ```python from broadcast_service import broadcast_service + # callback of common method def handle_msg(params): - print(params) + print(f"handle_msg receive params: {params}") # callback of decorator @broadcast_service.on_listen(['my_topic']) def handle_decorator_msg(params): - print(params) + print(f"handle_decorator_msg receive params: {params}") if __name__ == '__main__': info = 'This is very important msg' @@ -56,7 +57,6 @@ if __name__ == '__main__': # publish broadcast broadcast_service.publish('my_topic', info) - ``` **About more example, please see [Quick Start](/quickstart.md)** diff --git a/docs/_coverpage.md b/docs/_coverpage.md index ec7b75b..6271ec3 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -25,4 +25,4 @@ - Provide different syntax writing modes for lambda, callback functions, decorators, etc [GitHub](https://github.com/Undertone0809/broadcast-service) -[Getting Started](/broadcast-service.md) +[Getting Started](/README.md) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 807fabb..b558068 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,5 +1,5 @@ - Introduction - - [broadcast-service](broadcast-service.md) + - [broadcast-service](README.md) - Getting started @@ -8,5 +8,6 @@ - Other + - [Update](update.md) - [Plan](plan.md) - [Contribution](contribution.md) diff --git a/docs/broadcast-service.md b/docs/broadcast-service.md deleted file mode 100644 index cb5df3f..0000000 --- a/docs/broadcast-service.md +++ /dev/null @@ -1,73 +0,0 @@ -

- broadcast-service -

-

- A lightweight python broadcast library. You can easily construct a Broadcast pattern/Publish subscriber pattern through this library. -

- -

- - - - - github stars - - - - - - - -

- - -## Features -- A publishing subscriber pattern can be built with a very simple syntax -- Support different application scenarios, such as asynchronous and synchronous -- Provide different syntax writing modes for lambda, callback functions, decorators, etc -- A callback function listens on multiple subscriptions - -## Setup -```sh -pip install broadcast-service -``` - - -## Usage -There is a easy demo to show how to use broadcast-service. -```python -from broadcast_service import broadcast_service - -# callback of common method -def handle_msg(params): - print(params) - - -# callback of decorator -@broadcast_service.on_listen(['my_topic']) -def handle_decorator_msg(params): - print(params) - -if __name__ == '__main__': - info = 'This is very important msg' - - # subscribe topic - broadcast_service.subscribe('my_topic', handle_msg) - - # publish broadcast - broadcast_service.publish('my_topic', info) - -``` - -**About more example, please see [Quick Start](/quickstart.md)** - -## TODO -- optimize documents and show more examples. -- ~~optimize the syntax expression of broadcast-service~~ -- provide more test cases -- privide the ability to subscribe the topic and callback once -- Support for fuzzy subscriptions - - -## Contribution -If you want to contribute to this project, you can submit pr or issue. I am glad to see more people involved and optimize it. diff --git a/docs/quickstart.md b/docs/quickstart.md index da624fd..6313972 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,16 +1,20 @@ # Quick start ## Install -It is recommended to install latest version, which provides more features and less bugs. Old version is shit. +It is recommended to install latest version, which provides more features and less bugs. The old version is shit. ```bash pip install --upgrade broadcast-service ``` -## Initialize +## Example `broadcast-service` use single pattern to build the broadcast pattern/pubsub pattern, which means you can use it like a util class and you didn't initialize any other redundant class. -Now we create a easy pubsub pattern. +

+ +

+ +**Now you can see a easy pubsub pattern.** ```python from broadcast_service import broadcast_service @@ -31,45 +35,113 @@ if __name__ == '__main__': ``` -## Decorator -Moreover, it is recommend to use decorator to listen your topic. +> :warning: Attention: `listen` and `subscribe` mean the same thing in the following passage. + +## How to subscribe? +Actually, `broadcast-service` support mutiple subscirbe and publish methods, such as `common callback function` and `decorator`. You can see more example as follows. + +- **subscribe single topic** ```python from broadcast_service import broadcast_service -# callback of decorator +# common callback function method +def handle_msg(params): + print(params) + + +# decorator method @broadcast_service.on_listen(['my_topic']) -def handle_decorator_msg(params): +def handle_decorator_msg1(params): + print(params) + + +# if you just listen one topic, you don't have to pass a topic list +@broadcast_service.on_listen("my_topic") +def handle_decorator_msg2(params): print(params) if __name__ == '__main__': info = 'This is very important msg' + # subscribe topic + broadcast_service.subscribe('my_topic', handle_msg) + # you can also pass a topics list to subscribe multiple topics + broadcast_service.subscribe(['my_topic'], handle_msg) + # publish broadcast broadcast_service.publish('my_topic', info) ``` -You can listen multiple topics by decorator. The function is called back whenever a topic is triggered. +- **subscribe multiple topics** + +

+ +

```python from broadcast_service import broadcast_service -# callback of decorator -@broadcast_service.on_listen(['my_topic']) -def handle_decorator_msg(): - pass +def handle_msg(params): + print(params) + + +@broadcast_service.on_listen(['my_topic1', 'my_topic2']) +def handle_decorator_msg(params): + print(params) if __name__ == '__main__': - info = 'This is very important msg' + # This callback function is triggered when a message is sent from one of two topics subscribed to + broadcast_service.subscribe(['my_topic1', 'my_topic2'], handle_msg) # publish broadcast - broadcast_service.publish('my_topic') + broadcast_service.publish('my_topic1', "msg1") + broadcast_service.publish('my_topic2', "msg2") ``` +## How to publish? +You can pass multiple arguments to a topic or multiple topics by `broadcast-service`. You can see more example as follows. + +- **publish a topic** + +```python +from broadcast_service import broadcast_service + + +@broadcast_service.on_listen("no_param") +def handle_no_param(): + print("no param") + +broadcast_service.publish("no_param") + + +@broadcast_service.on_listen("one_param") +def handle_one_param(params): + print(params) + +broadcast_service.publish("one_param", 123) + + +@broadcast_service.on_listen("three_params") +def handle_three_params(a, b, c): + print(a) + print(b) + print(c) + +broadcast_service.publish("one_param", 11, 22, 33) + + +@broadcast_service.on_listen("multi_params") +def handle_multi_params(*args, **kwargs): + print(args) # [11, 22] + print(kwargs['msg']) # hello + +broadcast_service.publish("one_param", 11, 22, msg="hello") +``` ## Argument About argument, you'd better know how many arguments you should take. If your callback function arguments is different from the message arguments of your publish, you may not recevice the callback. Here are some example: @@ -141,14 +213,14 @@ if __name__ == '__main__': broadcast_service.publish('my_topic1', params=[11,22]) broadcast_service.publish('my_topic2', params={"msg": "success"}) ``` + **output:** + ```text {'params': [11, 22]} {'params': {'msg': 'success'}} ``` - - ## Attention You can use `publish, emit, broadcast` to send your topic msg. Using `listen, on, subscribe` to listen your topic msg. Using `stop_listen, off, unsubscribe` to cancel subscribe. diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 0000000..b8ab501 --- /dev/null +++ b/docs/update.md @@ -0,0 +1,82 @@ +# Update + +## Upgrade Version +Please update the latest version. The old version is shit. + +```bash +pip install --upgrade broadcast-service +``` + +## v1.2.0 2023-01-12 + +#### feat +1. Add support multiple publications and multiple subscriptions. + +```python +broadcast_service.publish(["topic1", "topic2"], "message") +``` + +2. Optimize the function of `broadcast_service.subscribe()` and `broadcast_service.publish()` + +- The following two cases are equivalent. + +```python +@broadcast_service.on_listen(['topic1']) +def handle_all_msg(): + # your code + +@broadcast_service.on_listen('topic1') +def handle_all_msg(): + # your code + +``` + +```python +broadcast_service.subscribe('topic1') +broadcast_service.subscribe(['topic1']) +``` + + +#### test +1. Add more test cases + + +## v1.1.7 2023-01-10 + +#### feat + +1. Add decorator, optimize syntactic expression [#5](https://github.com/Undertone0809/broadcast-service/pull/5) + +- You can use the following sentences to subscribe topic + +```python +@broadcast_service.on_listen(['topic1']) +def handle_all_msg(): + # your code + +@broadcast_service.on_listen(['topic1','topic2']) +def handle_all_msg(): + # your code + +@broadcast_service.on_listen() +def handle_all_msg(*args, **kwargs): + # your code +``` + +2. Add some equals function name + +```python +# send topic msg +broadcast_service.subscribe('my_topic', handle_msg) +broadcast_service.listen('my_topic', handle_msg) +broadcast_service.on('my_topic', handle_msg) + +# listen topic msg +broadcast_service.broadcast('my_topic', info) +broadcast_service.publish('my_topic', info) +broadcast_service.emit('my_topic', info) +``` + +#### test + +1. Optimize test cases and add some demo [#5](https://github.com/Undertone0809/broadcast-service/pull/5)