hijiki


Namehijiki JSON
Version 2.0.71 PyPI version JSON
download
home_pageNone
SummaryPython Rabbit wrapper library to simplify to use Exchanges and Queues with decorators
upload_time2025-07-25 19:13:50
maintainerNone
docs_urlNone
authorLeandro Vilson Battisti
requires_pythonNone
licenseNone
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"
}
        
Elapsed time: 1.56007s