| Name | hijiki JSON |
| Version |
2.0.71
JSON |
| download |
| home_page | None |
| Summary | Python Rabbit wrapper library to simplify to use Exchanges and Queues with decorators |
| upload_time | 2025-07-25 19:13:50 |
| maintainer | None |
| docs_url | None |
| author | Leandro Vilson Battisti |
| requires_python | None |
| license | None |
| keywords |
rabbitmq
decorator
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# HIJIKI - Gerenciamento de Mensagens com RabbitMQ
## 📚 Sobre a biblioteca HIJIKI
### Versão 2
Este documento descreve a biblioteca **HIJIKI** versão 2, que é uma evolução da versão 1, mantendo compatibilidade com o código existente. A versão 2 introduz melhorias significativas na estrutura e funcionalidade, mas não altera a API pública, garantindo que os usuários possam migrar facilmente sem necessidade de ajustes no código já implementado.
para acesso a versão 1, consulte a documentação da [versão 1](README_v1.md) e para fontes a tag v1_latest
HIJIKI é uma biblioteca Python de alto nível para gerenciamento de mensagens orientada a eventos, destinada a facilitar a criação, configuração e uso de consumidores e produtores de mensagens, principalmente utilizando **RabbitMQ** como broker. Seu objetivo é abstrair detalhes de implementação de fila e troca de mensagens, oferecendo uma interface intuitiva, flexível e adequada tanto para aplicações web quanto scripts standalone.
**Principais Características:**
- **Builder pattern** para configuração (`MessageManagerBuilder`), facilitando setup e customizações complexas.
- **Gerenciamento simplificado de consumidores**: registre consumidores (filas, tópicos e handlers) rapidamente usando uma API intuitiva.
- **Publicação fácil de mensagens**: uso direto de métodos para publicar em tópicos/fila, com suporte a mapeamento customizado de payloads.
- **Suporte a múltiplos brokers**: arquitetura pronta para suporte a outros brokers, embora os exemplos estejam focados em RabbitMQ.
- **Extensível**: pode ser integrada a decorators e middlewares para aplicações async/web como FastAPI ou scripts tradicionais.
- **Métodos utilitários** para manutenção do ciclo de vida do consumo, verificação de saúde (`is_alive`), troca dinâmica do broker, e registro em execução.
**Principais Classes:**
- `MessageManagerBuilder`: Classe principal para construir e configurar a stack.
- `MessageManager`: Gerencia operações de envio e consumo de mensagens.
- `ConsumerData`: Estrutura que associa uma fila, tópico e função handler.
---
## 📦 Instalação
Clone este repositório e instale as dependências:
``` shell
git clone https://github.com/asengardeon/hijiki.git
cd hijiki
pipenv install
```
## ⚙️ Detalhamento técnico dos métodos de uso
A seguir, um resumo técnico dos principais métodos empregados para utilizar a biblioteca HIJIKI na prática:
## 1. Criação e configuração do Manager
A configuração é feita via padrão builder, permitindo customização das conexões e parâmetros:
```
python
manager = (
MessageManagerBuilder()
.with_host("localhost")
.with_port(5672)
.with_user("user")
.with_password("pwd")
# outras opções, como troca do broker, etc.
.build()
)
```
- **with_host(host: str)**: define o endereço do broker RabbitMQ.
- **with_port(port: int)**: configura a porta de conexão.
- **with_user(user: str), with_password(password: str)**: definem credenciais.
- **build()**: instancia o manager, pronto para uso.
## 2. Registro de consumidores
### Criando consumidor manualmente
É preciso criar uma instância de `ConsumerData` associando uma fila, tópico e função de processamento.
O método **create_consumer** adiciona consumidores ao manager:
```
python
def process_message(msg):
print(f"Mensagem recebida: {msg}")
consumer_data = ConsumerData("nome_da_fila", "nome_do_topico", process_message)
manager.create_consumer(consumer_data)
```
- O handler (função) será chamada a cada mensagem recebida nessa fila/tópico.
##Criando consumidor com decorator
Você também pode usar o decorator `@consumer_handler` para registrar consumidores de forma mais simples:
### Modelo apenas determinando a fila
```
@consumer_handler(queue_name="teste1")
def internal_consumer(data):
print(f"consumiu o valor:{data}")
result_data_list.append(data)
result_event_list.append('received event')
```
### Modelo determinando fila e que não cria fila DLQ automaticamente, aconselhado para consumidores dde filas DLQ
```
@consumer_handler(queue_name="teste1_dlq", create_dlq=False)
def internal_consumer_dlq(data):
print(f"consumiu o valor:{data}")
result_event_list_dlq.append('received event')
```
### Modelo determinando fila e tópico
```
@consumer_handler(queue_name="fila_erro", topic="erro_event")
def internal_consumer_erro(data):
print(f"consumiu o valor:{data}")
result_event_list.append('received event')
raise Exception("falhou")
```
### Modelos com uso de routing_key
```
@consumer_handler(queue_name="teste_with_specific_routing_key", topic='teste1_event',
routing_key="specific_routing_key")
def internal_consumer(data):
print(f"consumiu o valor:{data}")
result_data_list.append(data)
result_data_list_dlq_for_specific_routing_key.append('received event')
```
## 3. Início do consumo
O método **start_consuming** inicia loops de consumo das filas para todos consumidores registrados:
```
python
manager.start_consuming()
```
- No FastAPI, recomenda-se executar em thread separada para não bloquear o servidor.
## 4. Publicação de mensagens
O método **publish** envia mensagens diretamente para a fila/ tópico definido:
```
python
manager.publish("nome_da_fila", "Conteúdo da mensagem")
```
- Mensagens podem ser publicadas a partir de endpoints FastAPI ou scripts Python, conforme exemplo.
---
## 📦 Pré-requisitos
- **RabbitMQ** rodando na máquina local (`localhost:5672`) ou disponível remotamente.
- Dependências Python instaladas:
- `pipenv install` (na raiz do projeto)
- Bibliotecas necessárias: `pika`, `fastapi`, `uvicorn`, entre outras já incluídas no `Pipfile` do projeto.
---
## Estrutura dos Exemplos
- [`fastapi_example.py`](./fastapi_example.py)
Demonstra como criar endpoints FastAPI para publicar mensagens e inicializar consumidores utilizando HIJIKI.
- [`pure_python_example.py`](./pure_python_example.py)
Demonstra como publicar e consumir mensagens programaticamente, usando apenas Python puro, sem framework web.
---
## ▶️ Como executar os exemplos
### 1. Exemplo FastAPI
#### **Passo a passo**
1. **Suba o RabbitMQ** em sua máquina local (padrão: usuário `user`, senha `pwd`, porta `5672`)
Se usar outro usuário/senha/host, edite o exemplo conforme necessário.
2. **Execute o servidor FastAPI**:
```sh
uvicorn examples.fastapi_example:app --reload
```
3. **Interaja com a API**:
- Publique uma mensagem:
```sh
curl -X POST "http://localhost:8000/publish/fastapi_queue" -H "accept: application/json" -d "message=Olá do FastAPI"
```
- Veja os consumidores recebendo mensagens no terminal onde o servidor está rodando (mensagens são exibidas via print).
#### **Observações**
- O consumidor é registrado e inicializado automaticamente ao subir o FastAPI.
- O consumo roda em uma thread em paralelo ao servidor web.
---
### 2. Exemplo Python Puro
#### **Passo a passo**
1. **Suba o RabbitMQ** em sua máquina local (`localhost:5672`).
2. **Execute o script**:
```sh
python examples/pure_python_example.py
```
3. **Verifique a saída**:
- O script publica uma mensagem inicial, registra o consumidor e começa a consumir mensagens da fila `python_queue`.
- O consumidor imprime no console todas as mensagens recebidas.
#### **Observações**
- Use `Ctrl+C` para interromper o consumo.
---
## 💡 Dicas e Customizações
- Para consumir de outras filas ou alterar tópicos, edite os nomes nos exemplos.
- Você pode registrar múltiplos consumidores, basta criar mais instâncias de `ConsumerData` e passar para `manager.create_consumer()`.
- Troque usuário, senha ou porta caso sua instância RabbitMQ seja diferente.
---
## 🛠️ Sobre a arquitetura utilizada
- Os consumidores são instâncias de `ConsumerData`, que associam fila, tópico e função de processamento.
- O método `manager.start_consuming()` inicia o consumo registrado para as filas configuradas.
- O exemplo FastAPI utiliza um thread para que o consumo de mensagens ocorra junto do serviço web.
---
## ❓ Dúvidas ou Sugestões?
Abra uma issue no repositório principal do projeto, ou envie sugestões/contribuições!
---
Raw data
{
"_id": null,
"home_page": null,
"name": "hijiki",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "RabbitMQ, decorator",
"author": "Leandro Vilson Battisti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/21/5b/97f828eb6f6e83dd162c2ab7de95cdaca164bc024b21b55b9ba56a5c13e0/hijiki-2.0.71.tar.gz",
"platform": null,
"description": "# HIJIKI - Gerenciamento de Mensagens com RabbitMQ\n## \ud83d\udcda Sobre a biblioteca HIJIKI\n\n### Vers\u00e3o 2\nEste documento descreve a biblioteca **HIJIKI** vers\u00e3o 2, que \u00e9 uma evolu\u00e7\u00e3o da vers\u00e3o 1, mantendo compatibilidade com o c\u00f3digo existente. A vers\u00e3o 2 introduz melhorias significativas na estrutura e funcionalidade, mas n\u00e3o altera a API p\u00fablica, garantindo que os usu\u00e1rios possam migrar facilmente sem necessidade de ajustes no c\u00f3digo j\u00e1 implementado.\npara acesso a vers\u00e3o 1, consulte a documenta\u00e7\u00e3o da [vers\u00e3o 1](README_v1.md) e para fontes a tag v1_latest\n\nHIJIKI \u00e9 uma biblioteca Python de alto n\u00edvel para gerenciamento de mensagens orientada a eventos, destinada a facilitar a cria\u00e7\u00e3o, configura\u00e7\u00e3o e uso de consumidores e produtores de mensagens, principalmente utilizando **RabbitMQ** como broker. Seu objetivo \u00e9 abstrair detalhes de implementa\u00e7\u00e3o de fila e troca de mensagens, oferecendo uma interface intuitiva, flex\u00edvel e adequada tanto para aplica\u00e7\u00f5es web quanto scripts standalone.\n\n**Principais Caracter\u00edsticas:**\n- **Builder pattern** para configura\u00e7\u00e3o (`MessageManagerBuilder`), facilitando setup e customiza\u00e7\u00f5es complexas.\n- **Gerenciamento simplificado de consumidores**: registre consumidores (filas, t\u00f3picos e handlers) rapidamente usando uma API intuitiva.\n- **Publica\u00e7\u00e3o f\u00e1cil de mensagens**: uso direto de m\u00e9todos para publicar em t\u00f3picos/fila, com suporte a mapeamento customizado de payloads.\n- **Suporte a m\u00faltiplos brokers**: arquitetura pronta para suporte a outros brokers, embora os exemplos estejam focados em RabbitMQ.\n- **Extens\u00edvel**: pode ser integrada a decorators e middlewares para aplica\u00e7\u00f5es async/web como FastAPI ou scripts tradicionais.\n- **M\u00e9todos utilit\u00e1rios** para manuten\u00e7\u00e3o do ciclo de vida do consumo, verifica\u00e7\u00e3o de sa\u00fade (`is_alive`), troca din\u00e2mica do broker, e registro em execu\u00e7\u00e3o.\n\n**Principais Classes:**\n- `MessageManagerBuilder`: Classe principal para construir e configurar a stack.\n- `MessageManager`: Gerencia opera\u00e7\u00f5es de envio e consumo de mensagens.\n- `ConsumerData`: Estrutura que associa uma fila, t\u00f3pico e fun\u00e7\u00e3o handler.\n\n---\n\n## \ud83d\udce6 Instala\u00e7\u00e3o\nClone este reposit\u00f3rio e instale as depend\u00eancias:\n\n``` shell\ngit clone https://github.com/asengardeon/hijiki.git\ncd hijiki\npipenv install \n```\n\n## \u2699\ufe0f Detalhamento t\u00e9cnico dos m\u00e9todos de uso\n\nA seguir, um resumo t\u00e9cnico dos principais m\u00e9todos empregados para utilizar a biblioteca HIJIKI na pr\u00e1tica:\n\n## 1. Cria\u00e7\u00e3o e configura\u00e7\u00e3o do Manager\n\nA configura\u00e7\u00e3o \u00e9 feita via padr\u00e3o builder, permitindo customiza\u00e7\u00e3o das conex\u00f5es e par\u00e2metros:\n```\npython\nmanager = (\n MessageManagerBuilder()\n .with_host(\"localhost\")\n .with_port(5672)\n .with_user(\"user\")\n .with_password(\"pwd\")\n # outras op\u00e7\u00f5es, como troca do broker, etc.\n .build()\n)\n```\n- **with_host(host: str)**: define o endere\u00e7o do broker RabbitMQ.\n- **with_port(port: int)**: configura a porta de conex\u00e3o.\n- **with_user(user: str), with_password(password: str)**: definem credenciais.\n- **build()**: instancia o manager, pronto para uso.\n\n## 2. Registro de consumidores\n### Criando consumidor manualmente\n\u00c9 preciso criar uma inst\u00e2ncia de `ConsumerData` associando uma fila, t\u00f3pico e fun\u00e7\u00e3o de processamento. \nO m\u00e9todo **create_consumer** adiciona consumidores ao manager:\n```\npython\ndef process_message(msg):\n print(f\"Mensagem recebida: {msg}\")\n\nconsumer_data = ConsumerData(\"nome_da_fila\", \"nome_do_topico\", process_message)\nmanager.create_consumer(consumer_data)\n```\n- O handler (fun\u00e7\u00e3o) ser\u00e1 chamada a cada mensagem recebida nessa fila/t\u00f3pico.\n\n##Criando consumidor com decorator\nVoc\u00ea tamb\u00e9m pode usar o decorator `@consumer_handler` para registrar consumidores de forma mais simples:\n\n### Modelo apenas determinando a fila\n```\n@consumer_handler(queue_name=\"teste1\")\n def internal_consumer(data):\n print(f\"consumiu o valor:{data}\")\n result_data_list.append(data)\n result_event_list.append('received event')\n```\n### Modelo determinando fila e que n\u00e3o cria fila DLQ automaticamente, aconselhado para consumidores dde filas DLQ \n```\n @consumer_handler(queue_name=\"teste1_dlq\", create_dlq=False)\n def internal_consumer_dlq(data):\n print(f\"consumiu o valor:{data}\")\n result_event_list_dlq.append('received event')\n```\n### Modelo determinando fila e t\u00f3pico\n```\n @consumer_handler(queue_name=\"fila_erro\", topic=\"erro_event\")\n def internal_consumer_erro(data):\n print(f\"consumiu o valor:{data}\")\n result_event_list.append('received event')\n raise Exception(\"falhou\")\n```\n### Modelos com uso de routing_key\n```\n @consumer_handler(queue_name=\"teste_with_specific_routing_key\", topic='teste1_event',\n routing_key=\"specific_routing_key\")\n def internal_consumer(data):\n print(f\"consumiu o valor:{data}\")\n result_data_list.append(data)\n result_data_list_dlq_for_specific_routing_key.append('received event')\n```\n\n## 3. In\u00edcio do consumo\n\nO m\u00e9todo **start_consuming** inicia loops de consumo das filas para todos consumidores registrados:\n```\npython\nmanager.start_consuming()\n```\n- No FastAPI, recomenda-se executar em thread separada para n\u00e3o bloquear o servidor.\n\n## 4. Publica\u00e7\u00e3o de mensagens\n\nO m\u00e9todo **publish** envia mensagens diretamente para a fila/ t\u00f3pico definido:\n```\npython\nmanager.publish(\"nome_da_fila\", \"Conte\u00fado da mensagem\")\n```\n- Mensagens podem ser publicadas a partir de endpoints FastAPI ou scripts Python, conforme exemplo.\n\n---\n\n## \ud83d\udce6 Pr\u00e9-requisitos\n\n- **RabbitMQ** rodando na m\u00e1quina local (`localhost:5672`) ou dispon\u00edvel remotamente.\n- Depend\u00eancias Python instaladas:\n - `pipenv install` (na raiz do projeto)\n - Bibliotecas necess\u00e1rias: `pika`, `fastapi`, `uvicorn`, entre outras j\u00e1 inclu\u00eddas no `Pipfile` do projeto.\n\n---\n\n## Estrutura dos Exemplos\n\n- [`fastapi_example.py`](./fastapi_example.py) \n Demonstra como criar endpoints FastAPI para publicar mensagens e inicializar consumidores utilizando HIJIKI.\n\n- [`pure_python_example.py`](./pure_python_example.py) \n Demonstra como publicar e consumir mensagens programaticamente, usando apenas Python puro, sem framework web.\n\n---\n\n## \u25b6\ufe0f Como executar os exemplos\n\n### 1. Exemplo FastAPI\n\n#### **Passo a passo**\n\n1. **Suba o RabbitMQ** em sua m\u00e1quina local (padr\u00e3o: usu\u00e1rio `user`, senha `pwd`, porta `5672`) \n Se usar outro usu\u00e1rio/senha/host, edite o exemplo conforme necess\u00e1rio.\n\n2. **Execute o servidor FastAPI**:\n ```sh\n uvicorn examples.fastapi_example:app --reload\n ```\n3. **Interaja com a API**:\n - Publique uma mensagem:\n ```sh\n curl -X POST \"http://localhost:8000/publish/fastapi_queue\" -H \"accept: application/json\" -d \"message=Ol\u00e1 do FastAPI\"\n ```\n - Veja os consumidores recebendo mensagens no terminal onde o servidor est\u00e1 rodando (mensagens s\u00e3o exibidas via print).\n\n#### **Observa\u00e7\u00f5es**\n- O consumidor \u00e9 registrado e inicializado automaticamente ao subir o FastAPI.\n- O consumo roda em uma thread em paralelo ao servidor web.\n\n---\n\n### 2. Exemplo Python Puro\n\n#### **Passo a passo**\n\n1. **Suba o RabbitMQ** em sua m\u00e1quina local (`localhost:5672`).\n\n2. **Execute o script**:\n ```sh\n python examples/pure_python_example.py\n ```\n\n3. **Verifique a sa\u00edda**:\n - O script publica uma mensagem inicial, registra o consumidor e come\u00e7a a consumir mensagens da fila `python_queue`.\n - O consumidor imprime no console todas as mensagens recebidas.\n\n#### **Observa\u00e7\u00f5es**\n- Use `Ctrl+C` para interromper o consumo.\n\n---\n\n## \ud83d\udca1 Dicas e Customiza\u00e7\u00f5es\n\n- Para consumir de outras filas ou alterar t\u00f3picos, edite os nomes nos exemplos.\n- Voc\u00ea pode registrar m\u00faltiplos consumidores, basta criar mais inst\u00e2ncias de `ConsumerData` e passar para `manager.create_consumer()`.\n- Troque usu\u00e1rio, senha ou porta caso sua inst\u00e2ncia RabbitMQ seja diferente.\n\n---\n\n## \ud83d\udee0\ufe0f Sobre a arquitetura utilizada\n\n- Os consumidores s\u00e3o inst\u00e2ncias de `ConsumerData`, que associam fila, t\u00f3pico e fun\u00e7\u00e3o de processamento.\n- O m\u00e9todo `manager.start_consuming()` inicia o consumo registrado para as filas configuradas.\n- O exemplo FastAPI utiliza um thread para que o consumo de mensagens ocorra junto do servi\u00e7o web.\n\n---\n\n## \u2753 D\u00favidas ou Sugest\u00f5es?\n\nAbra uma issue no reposit\u00f3rio principal do projeto, ou envie sugest\u00f5es/contribui\u00e7\u00f5es!\n\n---\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Rabbit wrapper library to simplify to use Exchanges and Queues with decorators",
"version": "2.0.71",
"project_urls": null,
"split_keywords": [
"rabbitmq",
" decorator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "07820ac65a80c619f82672f38eb45da4934248fcabc8191ae6384b4caf194032",
"md5": "e2eeccdcfa24c4f492be74d8270bde5e",
"sha256": "9eb5b78853bbd3af8907c60f0fea97a194b3043483830107aea6ad17159757dd"
},
"downloads": -1,
"filename": "hijiki-2.0.71-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2eeccdcfa24c4f492be74d8270bde5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26762,
"upload_time": "2025-07-25T19:13:49",
"upload_time_iso_8601": "2025-07-25T19:13:49.987052Z",
"url": "https://files.pythonhosted.org/packages/07/82/0ac65a80c619f82672f38eb45da4934248fcabc8191ae6384b4caf194032/hijiki-2.0.71-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "215b97f828eb6f6e83dd162c2ab7de95cdaca164bc024b21b55b9ba56a5c13e0",
"md5": "cbc99be3ac7ebce0bde574b6bd59950b",
"sha256": "12730f67a537739ac81849b9d0fafc2d52ebb4c9f9cd751aa1079a4ea4760fe6"
},
"downloads": -1,
"filename": "hijiki-2.0.71.tar.gz",
"has_sig": false,
"md5_digest": "cbc99be3ac7ebce0bde574b6bd59950b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28776,
"upload_time": "2025-07-25T19:13:50",
"upload_time_iso_8601": "2025-07-25T19:13:50.728256Z",
"url": "https://files.pythonhosted.org/packages/21/5b/97f828eb6f6e83dd162c2ab7de95cdaca164bc024b21b55b9ba56a5c13e0/hijiki-2.0.71.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 19:13:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hijiki"
}
