PyChannel 0.1.0__py3-none-any.whl

PyChannel/__init__.py

@@ -0,0 +1,7 @@
+from .task import Task
+from .channel import Channel
+from .buffer import Buffer
+
+__version__ = "0.1.0"
+
+__all__ = ["Task", "Channel", "Buffer", "__version__"]

PyChannel/buffer.py

@@ -0,0 +1,68 @@
+import logging
+import time
+from threading import RLock
+from typing import Any
+
+import PyChannel.global_logs as global_logs
+
+logger = logging.getLogger(__name__)
+
+
+class Buffer:
+    def __init__(self, capacity: int, timeout: int, name: str = None) -> None:
+        self.cap = capacity
+        self.time = timeout
+        self.queue = []
+        self.name = name if name is not None else "Buffer"
+        self.time_init = None
+        self.lock = RLock()
+
+    #Envia o dado pra queue do buffer
+    def sender(self, data: Any) -> None:
+        with self.lock:
+            if len(self.queue) == 0:
+                self.time_init = time.monotonic()
+
+            if len(self.queue) < self.cap:
+                logger.info(f"Adding data to {self.name}...")
+                self.queue.append(data)
+                logger.info("Added!!")
+                return
+
+        logger.warning(f"{self.name} exceeded the limit!!!")
+
+    #Retorna a queue
+    def get(self) -> list:
+        with self.lock:
+            return self.queue
+
+    #Retorna o status do buffer, sele ele tiver excedidio o tempo, ou atingido o limite, ai retorna True
+    def status(self) -> bool:
+        with self.lock:
+            if self.time_init is None:
+                logger.warning(
+                    f"It is not yet possible to check the status of {self.name}, "
+                    "because the queue has not received data to start the timer!!"
+                )
+                return False
+
+            if time.monotonic() - self.time_init >= self.time:
+                logger.info(f"{self.name} exceeded the execution time limit!!")
+                return True
+
+            if len(self.queue) >= self.cap:
+                logger.info(f"{self.name} exceeded the storage limit!!")
+                return True
+
+            return False
+
+
+    #Reseta a queue do buffer
+    def reset(self) -> None:
+        logger.info(f"Resetting {self.name}...")
+
+        with self.lock:
+            self.queue.clear()
+            self.time_init = None
+
+        logger.info("Reset!!")

PyChannel/channel.py

@@ -0,0 +1,39 @@
+#Pega a configuração global de logs
+import logging
+
+import PyChannel.global_logs as global_logs
+
+logger = logging.getLogger(__name__)
+
+
+from multiprocessing import Queue
+from typing import Any
+
+#Cria o canal para pegar os resultados das tasks
+class Channel:
+    def __init__(self, name: str = None, limit: int = None) -> None:
+        self.name = name if name is not None else "Channel"
+        logging.info(f"{self.name} created!!")
+        self.queue = Queue() if limit is None else Queue(maxsize=limit)
+
+    #Envia resultado pra queue
+    def send(self, result: Any) -> None:
+        logger.info(f"Sending result to {self.name if self.name is not None else 'Channel'}...")
+        self.queue.put(result)
+        logger.info("Sent!!!")
+        
+    
+    #Pega o resultado da queue, e se loop for True, ele vai retornar o resultado da queue só quando não for false
+    def get(self, loop:bool = None) -> Any:
+        logger.info(f"Waiting for result from {self.name if self.name is not None else 'Channel'}...")
+        if loop:
+            logger.info(f"Waiting for the true result...")
+            while True:
+                
+                result = self.queue.get()
+                if result:
+                    break
+        else:
+            result = self.queue.get()
+        logger.info("Result found!!!")
+        return result

PyChannel/global_logs.py

@@ -0,0 +1,10 @@
+# Configures global logging
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)s | %(message)s",
+    handlers=[
+        logging.StreamHandler()
+    ]
+)

PyChannel/task.py

@@ -0,0 +1,69 @@
+import logging
+from concurrent.futures import Future
+from functools import wraps
+from typing import Any
+
+import PyChannel.global_logs as global_logs
+from loky import get_reusable_executor
+
+from PyChannel.buffer import Buffer
+from PyChannel.channel import Channel
+
+#Pega a configuração de logs
+logger = logging.getLogger(__name__)
+
+#Cria tasks
+class Task:
+    def __init__(
+        self,
+        max_workers: int,
+        name: str = None,
+        channel: Channel = None,
+        buffer: Buffer = None,
+    ) -> None:
+        self.name = name if name is not None else "task"
+        self.ch = channel
+        self.buff = buffer
+        self.process = get_reusable_executor(max_workers=max_workers)
+
+    def _finished(self, future: Future[Any]) -> None:
+        try:
+            result = future.result()
+        except Exception as error:
+            if self.ch is not None:
+                self.ch.send(result=error)
+            return
+
+        if self.buff is None:
+            if self.ch is not None:
+                self.ch.send(result=result)
+            return
+
+        output: Any = False
+
+        with self.buff.lock:
+            self.buff.sender(data=result)
+
+            if self.buff.status():
+                output = self.buff.get().copy()
+                self.buff.reset()
+
+        if self.ch is not None:
+            self.ch.send(result=output)
+
+    def run(self):
+        logger.info(f"Starting {self.name}...")
+
+        def decorator(func):
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                future = self.process.submit(func, *args, **kwargs)
+
+                if self.ch is not None or self.buff is not None:
+                    future.add_done_callback(self._finished)
+
+                return future
+
+            return wrapper
+
+        return decorator

pychannel-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: PyChannel
+Version: 0.1.0
+Summary: A Python concurrency library inspired by Go's goroutines and channels
+Author: Brayan
+Keywords: concurrency,channels,goroutines,parallelism,multiprocessing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: loky<4,>=3.5.6
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+
+# PyChannel
+
+![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![Versão](https://img.shields.io/badge/vers%C3%A3o-0.1.0-2ea44f?style=for-the-badge)
+![Status](https://img.shields.io/badge/status-alpha-orange?style=for-the-badge)
+![Concorrência](https://img.shields.io/badge/concorr%C3%AAncia-loky-6f42c1?style=for-the-badge)
+
+**PyChannel** é uma biblioteca de concorrência inspirada nas goroutines e nos channels da linguagem Go. Sua API é composta por três módulos principais: `Task`, `Channel` e `Buffer`.
+
+> A PyChannel utiliza processos gerenciados pelo `loky`. Ela é inspirada nos conceitos do Go, mas não implementa goroutines reais.
+
+## Fluxo de execução
+
+```mermaid
+flowchart LR
+    A["Função decorada"] --> B["Task"]
+    B --> C["Worker do loky"]
+    C --> D["Future"]
+    D --> E{"Buffer configurado?"}
+    E -- "Não" --> F["Channel recebe o resultado"]
+    E -- "Sim, acumulando" --> G["Channel recebe False"]
+    E -- "Sim, lote pronto" --> H["Channel recebe a lista"]
+```
+
+A `Task` envia a função para um worker. O resultado retorna por um `Future` e, quando configurado, também é encaminhado ao `Channel`. Se a `Task` possuir um `Buffer`, os resultados são acumulados antes da liberação do lote.
+
+## `Task`
+
+A classe `Task` transforma uma função comum em uma tarefa executada por processos.
+
+```python
+Task(
+    max_workers,
+    name=None,
+    channel=None,
+    buffer=None,
+)
+```
+
+| Parâmetro | Função |
+| --- | --- |
+| `max_workers` | Define a quantidade máxima de processos disponíveis no pool. |
+| `name` | Define o nome da tarefa exibido nos logs. |
+| `channel` | Recebe os resultados e as exceções das execuções. |
+| `buffer` | Ativa o agrupamento automático dos resultados. |
+
+### Decorando uma função
+
+O método `run()` retorna o decorator responsável por enviar cada chamada ao executor:
+
+```python
+from PyChannel import Channel, Task
+
+channel = Channel(name="Resultados")
+task = Task(max_workers=4, name="Cálculos", channel=channel)
+
+
+@task.run()
+def quadrado(numero):
+    return numero * numero
+
+
+future = quadrado(10)
+```
+
+A chamada não devolve o resultado diretamente. Ela devolve um `Future`:
+
+```python
+resultado = future.result()  # 100
+```
+
+Como existe um `Channel`, o mesmo resultado também pode ser consumido por ele:
+
+```python
+resultado = channel.get()  # 100
+```
+
+### Comportamento da Task
+
+| Configuração | Comportamento |
+| --- | --- |
+| Sem `Channel` e sem `Buffer` | O resultado fica disponível somente no `Future`. |
+| Com `Channel` | Cada resultado é enviado ao Channel. |
+| Com `Channel` e `Buffer` | O Channel recebe `False` durante o acúmulo e uma lista quando o lote fica pronto. |
+| Com `Buffer`, sem `Channel` | O Buffer é atualizado e o resultado individual continua disponível no `Future`. |
+
+Se a função gerar uma exceção, ela permanece armazenada no `Future`. Quando existe um Channel, o objeto da exceção também é enviado para ele.
+
+## `Channel`
+
+O `Channel` transporta valores entre produtores e consumidores por meio de uma `multiprocessing.Queue`.
+
+```python
+Channel(name=None, limit=None)
+```
+
+| Parâmetro | Função |
+| --- | --- |
+| `name` | Define o nome utilizado nos logs. |
+| `limit` | Define a quantidade máxima de valores pendentes. `None` cria uma fila sem limite explícito. |
+
+### Enviando e recebendo valores
+
+```python
+from PyChannel import Channel
+
+channel = Channel(name="Eventos")
+
+channel.send("processado")
+resultado = channel.get()
+
+print(resultado)  # processado
+```
+
+`send()` bloqueia se um Channel limitado estiver cheio. `get()` bloqueia enquanto não houver nenhum valor disponível.
+
+### Ignorando resultados falsos
+
+O método `get(loop=True)` continua consumindo a fila até encontrar um valor verdadeiro:
+
+```python
+resultado = channel.get(loop=True)
+```
+
+Esse modo é útil com o Buffer automático, pois ignora os valores `False` enviados durante o acúmulo e retorna diretamente o lote:
+
+```python
+somar()
+somar()
+
+lote = channel.get(loop=True)
+print(lote)  # [2, 2]
+```
+
+> `loop=True` ignora qualquer valor considerado falso pelo Python, incluindo `False`, `None`, `0`, `""` e coleções vazias.
+
+## `Buffer`
+
+O `Buffer` acumula valores temporariamente até atingir sua capacidade ou seu limite de tempo.
+
+```python
+Buffer(capacity, timeout, name=None)
+```
+
+| Parâmetro | Função |
+| --- | --- |
+| `capacity` | Quantidade máxima de valores acumulados. |
+| `timeout` | Tempo máximo, em segundos, contado a partir do primeiro valor. |
+| `name` | Define o nome utilizado nos logs. |
+
+O acesso interno é protegido por um `RLock`, permitindo chamadas concorrentes aos seus métodos.
+
+### Uso manual
+
+```python
+from PyChannel import Buffer
+
+buffer = Buffer(capacity=3, timeout=10, name="Lote")
+
+buffer.sender("A")
+buffer.sender("B")
+
+print(buffer.status())  # False
+
+buffer.sender("C")
+
+if buffer.status():
+    lote = buffer.get().copy()
+    buffer.reset()
+    print(lote)  # ["A", "B", "C"]
+```
+
+### Métodos
+
+| Método | Comportamento |
+| --- | --- |
+| `sender(data)` | Adiciona um valor se ainda houver capacidade. O contador de tempo começa no primeiro valor. |
+| `get()` | Retorna a lista atualmente armazenada. |
+| `status()` | Retorna `True` quando a capacidade ou o timeout é atingido. |
+| `reset()` | Limpa a lista e reinicia o controle de tempo. |
+
+O timeout não cria uma tarefa em segundo plano. Ele é avaliado quando `status()` é chamado ou quando a `Task` processa um novo resultado.
+
+## Integração dos módulos
+
+```python
+from PyChannel import Buffer, Channel, Task
+
+buffer = Buffer(capacity=2, timeout=10, name="Resultados")
+channel = Channel(name="Saída")
+task = Task(
+    max_workers=2,
+    name="Soma",
+    channel=channel,
+    buffer=buffer,
+)
+
+
+@task.run()
+def somar(a, b):
+    return a + b
+
+
+somar(1, 1)
+somar(2, 2)
+
+lote = channel.get(loop=True)
+print(lote)  # A ordem pode ser [2, 4] ou [4, 2]
+```
+
+Os workers executam de forma independente. Por isso, os resultados chegam ao Buffer e ao Channel na ordem de conclusão, não necessariamente na ordem de envio.

pychannel-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+PyChannel/__init__.py,sha256=zdL_R3Zzt3pS92qvOTiEfmgGYKyEzajg39W03-uUl4o,165
+PyChannel/buffer.py,sha256=daUlFtYl3rXwQSULF_QabHSMZ7HXAHaYXcieS5G86V8,2105
+PyChannel/channel.py,sha256=fE6eWnVkYAa33j1yjtOWVAtN8Rsh9AEBA5F-_A-l_KY,1381
+PyChannel/global_logs.py,sha256=cHXuh54g-Poog35uZemFNC83Ive8vTSUqX3rwPl_qgo,210
+PyChannel/task.py,sha256=DtYtbnBOQGWoV7q6h4nuDzqQbBSRRODi6tivIuqnfSI,1874
+pychannel-0.1.0.dist-info/METADATA,sha256=RtbzeAEQWJMIIM28KqB4dCxblOX9_i6Ms8fBkYl24zs,7225
+pychannel-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pychannel-0.1.0.dist-info/top_level.txt,sha256=P7oj5z4KKaGJmihfNMeboaBWP1aQj6ppTfdvFpPQOzI,10
+pychannel-0.1.0.dist-info/RECORD,,

pychannel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pychannel-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+PyChannel