dataloom-engine 0.3.0__py3-none-any.whl

dataloom_engine/__init__.py

@@ -0,0 +1,43 @@
+# dataloom_engine/__init__.py
+
+"""
+DataLoom: Um motor de orquestração multi-thread leve e eficiente.
+
+Este módulo expõe a API pública do pacote. Observe que classes internas
+como 'Weaver' não são expostas propositalmente, mantendo a superfície
+de uso limpa e segura para o consumidor.
+"""
+
+from dataloom_engine.config import LoomConfig
+from dataloom_engine.exceptions import ConfigurationError, LoomError, WeaverError
+from dataloom_engine.hooks import LoomHooks
+from dataloom_engine.logs import LoomLogs
+from dataloom_engine.loom import Loom
+from dataloom_engine.processors import Processor
+from dataloom_engine.sinks import (
+    CallbackSink,
+    CsvFileSink,
+    JsonFileSink,
+    Sink,
+    ThreadedBufferedSink,
+)
+from dataloom_engine.sources import Source
+from dataloom_engine.types import LoomState
+
+__all__ = [
+    "Loom",
+    "LoomConfig",
+    "LoomState",
+    "Processor",
+    "Sink",
+    "JsonFileSink",
+    "CsvFileSink",
+    "CallbackSink",
+    "ThreadedBufferedSink",
+    "Source",
+    "LoomHooks",
+    "LoomLogs",
+    "LoomError",
+    "WeaverError",
+    "ConfigurationError",
+]

dataloom_engine/config.py

@@ -0,0 +1,52 @@
+# dataloom_engine/config.py
+
+"""
+Gerenciamento de configuração do orquestrador.
+Centraliza parâmetros operacionais como diretórios e tamanhos de lote.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+from dataloom_engine.exceptions import ConfigurationError
+
+
+@dataclass
+class LoomConfig:
+    """
+    Objeto de configuração principal do DataLoom.
+
+    Args:
+        output_dir (Path): Diretório base onde os Sinks padrão salvarão dados.
+            Strings são convertidas para Path automaticamente.
+        batch_size (int): Quantidade de itens gerados por ciclo de processamento.
+        interval_seconds (float): Intervalo de tempo entre gerações de tarefas.
+        queue_maxsize (Optional[int]): Capacidade máxima da fila de tarefas
+            (backpressure). None usa o padrão do Loom (num_weavers * 4);
+            0 significa fila ilimitada.
+
+    Raises:
+        ConfigurationError: se algum parâmetro for inválido.
+    """
+
+    output_dir: Union[str, Path]
+    batch_size: int = 10
+    interval_seconds: float = 1.0
+    queue_maxsize: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        self.output_dir = Path(self.output_dir)
+
+        if self.batch_size <= 0:
+            raise ConfigurationError(
+                f"batch_size deve ser maior que zero (recebido: {self.batch_size})."
+            )
+        if self.interval_seconds < 0:
+            raise ConfigurationError(
+                f"interval_seconds não pode ser negativo (recebido: {self.interval_seconds})."
+            )
+        if self.queue_maxsize is not None and self.queue_maxsize < 0:
+            raise ConfigurationError(
+                f"queue_maxsize não pode ser negativo (recebido: {self.queue_maxsize})."
+            )

dataloom_engine/exceptions.py

@@ -0,0 +1,25 @@
+# dataloom_engine/exceptions.py
+
+"""
+Exceções personalizadas para o DataLoom.
+Permite que consumidores capturem erros específicos da biblioteca
+sem depender de exceções genéricas do Python.
+"""
+
+
+class LoomError(Exception):
+    """Exceção base para todos os erros do DataLoom."""
+
+    pass
+
+
+class ConfigurationError(LoomError):
+    """Lançado quando há problemas na validação do LoomConfig."""
+
+    pass
+
+
+class WeaverError(LoomError):
+    """Lançado quando um Weaver falha de forma irrecuperável."""
+
+    pass

dataloom_engine/hooks.py

@@ -0,0 +1,50 @@
+# dataloom_engine/hooks.py
+
+"""
+Pontos de extensão para observabilidade (Hooks).
+Permite injetar lógica de monitoramento sem acoplar ao core do engine.
+"""
+
+from typing import Any, Dict
+
+
+class LoomHooks:
+    """
+    Classe base para hooks do ciclo de vida.
+    Todos os métodos são opcionais e no-op por padrão: sobrescreva apenas
+    os pontos de interesse. (Deliberadamente não é um ABC — não há método
+    obrigatório a implementar.)
+    """
+
+    def on_start(self) -> None:
+        """Chamado imediatamente antes dos Weavers serem iniciados."""
+        pass
+
+    def on_stop(self) -> None:
+        """Chamado após o encerramento gracioso do orquestrador."""
+        pass
+
+    def on_error(self, error: Exception) -> None:
+        """
+        Chamado quando ocorre uma exceção no loop principal do Loom ou
+        durante o processamento de um lote em um Weaver (WeaverError).
+
+        Atenção: pode ser invocado a partir de múltiplas threads Weaver
+        simultaneamente — implementações devem ser thread-safe.
+        """
+        pass
+
+    def on_batch_processed(self, result: Dict[str, Any], duration_seconds: float) -> None:
+        """
+        Chamado após cada lote processado e entregue ao Sink com sucesso.
+
+        Args:
+            result: O dicionário produzido pelo Processor para o lote.
+            duration_seconds: Tempo gasto em process() + send(), medido
+                com relógio monotônico.
+
+        Atenção: assim como on_error, é invocado a partir das threads
+        Weaver — implementações devem ser thread-safe e rápidas, pois
+        rodam no caminho quente do pipeline.
+        """
+        pass

dataloom_engine/logs.py

@@ -0,0 +1,28 @@
+# dataloom_engine/logs.py
+
+"""
+Utilitários de configuração de logging para o DataLoom.
+Fornece um namespace estático para configuração rápida.
+"""
+
+import logging
+
+
+class LoomLogs:
+    """
+    Namespace utilitário para gerenciamento de logs do DataLoom.
+    Não deve ser instanciado, apenas usado estaticamente.
+    """
+
+    @staticmethod
+    def setup(level: int = logging.INFO) -> None:
+        """
+        Configura o logging básico para stdout.
+
+        Uso:
+            LoomLogs.setup(level=logging.DEBUG)
+        """
+        logging.basicConfig(
+            level=level,
+            format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        )

dataloom_engine/loom.py

@@ -0,0 +1,167 @@
+# dataloom_engine/loom.py
+
+"""
+O módulo Loom é o coração do motor de orquestração.
+Define a classe principal responsável por gerenciar o ciclo de vida
+das threads (Weavers) e a distribuição de tarefas.
+"""
+
+import queue
+import threading
+from typing import TYPE_CHECKING, Optional
+
+from dataloom_engine.config import LoomConfig
+from dataloom_engine.hooks import LoomHooks
+from dataloom_engine.processors import Processor
+from dataloom_engine.sinks import Sink
+from dataloom_engine.types import LoomState
+from dataloom_engine.weaver import STOP_SENTINEL, Weaver
+
+if TYPE_CHECKING:
+    from dataloom_engine.sources import Source
+
+
+class Loom:
+    """
+    Orquestrador principal do DataLoom.
+
+    Exemplo de uso:
+        config = LoomConfig(...)
+        loom = Loom(config, processor, sink)
+        loom.start()
+
+    Também pode ser usado como context manager, garantindo stop()
+    mesmo se o bloco levantar exceção ou for interrompido:
+        with Loom(config, processor, sink) as loom:
+            loom.start()
+    """
+
+    def __init__(
+        self,
+        config: LoomConfig,
+        processor: Processor,
+        sink: Sink,
+        source: Optional["Source"] = None,
+        hooks: Optional[LoomHooks] = None,
+        num_weavers: int = 2,
+    ):
+        self.config = config
+        self.processor = processor
+        self.sink = sink
+
+        # Default dependency injection if not provided
+        if source is None:
+            # Import tardio para evitar dependência circular no import do módulo
+            from dataloom_engine.sources import RandomNumPySource
+
+            source = RandomNumPySource(config)
+        self.source: "Source" = source
+
+        # Garante nova instância de hooks se não fornecida (evita estado global)
+        self.hooks = hooks or LoomHooks()
+        self.num_weavers = num_weavers
+
+        self.state = LoomState.PENDING
+
+        # Fila limitada (backpressure): se os Weavers não acompanharem o
+        # ritmo do Source, o produtor aguarda em vez de acumular memória.
+        # queue_maxsize=0 na config desliga o limite.
+        if config.queue_maxsize is not None:
+            maxsize = config.queue_maxsize
+        else:
+            maxsize = num_weavers * 4
+        self.task_queue: queue.Queue = queue.Queue(maxsize=maxsize)
+
+        self.stop_event = threading.Event()
+        self.weavers: list[Weaver] = []
+        self._stop_lock = threading.Lock()
+        self._stopped = False
+
+    def __enter__(self) -> "Loom":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        # Garante limpeza completa ao sair do bloco with, inclusive em
+        # exceções (como KeyboardInterrupt) que escapem do start().
+        # stop() é idempotente, então não há custo se já foi chamado.
+        self.stop()
+
+    def start(self) -> None:
+        """
+        Inicializa os Weavers e começa o loop de geração de tarefas.
+        Este método bloqueia a execução até que ocorra erro ou parada.
+        """
+        self.state = LoomState.RUNNING
+        self.hooks.on_start()
+
+        # Acorda os tecelões
+        for _ in range(self.num_weavers):
+            weaver = Weaver(
+                self.task_queue,
+                self.processor,
+                self.sink,
+                on_error=self.hooks.on_error,
+                on_batch_processed=self.hooks.on_batch_processed,
+            )
+            weaver.start()
+            self.weavers.append(weaver)
+
+        try:
+            # Consome do Source
+            for batch in self.source:
+                if self.stop_event.is_set():
+                    break
+                self._enqueue(batch)
+        except Exception as e:
+            self.state = LoomState.FAILED
+            self.hooks.on_error(e)
+            raise
+        finally:
+            self.stop()
+
+    def _enqueue(self, batch) -> None:
+        """
+        Coloca um lote na fila sem bloquear indefinidamente: o timeout
+        permite reagir a um stop() disparado por outra thread.
+        """
+        while not self.stop_event.is_set():
+            try:
+                self.task_queue.put(batch, timeout=0.1)
+                return
+            except queue.Full:
+                continue
+
+    def stop(self) -> None:
+        """
+        Sinaliza a parada de todos os componentes e aguarda limpeza.
+        Seguro para ser chamado múltiplas vezes ou dentro de blocos finally.
+
+        Os itens já enfileirados são processados antes do encerramento:
+        cada Weaver consome a fila até encontrar seu sentinela de parada.
+        """
+        with self._stop_lock:
+            if self._stopped:
+                return
+            self._stopped = True
+
+        self.stop_event.set()
+
+        # Um sentinela por Weaver: cada thread drena a fila e encerra
+        # ao consumir o seu. Isso substitui o join() na fila, que podia
+        # travar para sempre se um Weaver morresse antes de esvaziá-la.
+        for _ in self.weavers:
+            self.task_queue.put(STOP_SENTINEL)
+        for weaver in self.weavers:
+            weaver.join()
+
+        # Não sobrescreve FAILED definido pelo start() em caso de erro
+        if self.state is LoomState.RUNNING:
+            self.state = LoomState.COMPLETED
+
+        try:
+            self.sink.close()
+        except Exception as e:
+            # Não queremos que erro no close esconda outros erros, mas logamos
+            self.hooks.on_error(e)
+
+        self.hooks.on_stop()

dataloom_engine/processors.py

@@ -0,0 +1,43 @@
+# dataloom_engine/processors.py
+
+"""
+Contratos de processamento de dados.
+Define como os lotes (batches) são transformados antes de serem enviados ao Sink.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+import numpy as np
+
+
+class Processor(ABC):
+    """Interface base para transformação de dados."""
+
+    @abstractmethod
+    def process(self, batch: np.ndarray) -> Dict[str, Any]:
+        """
+        Processa um lote de dados.
+
+        Args:
+            batch: Array contendo os dados brutos (tamanho definido em LoomConfig).
+
+        Returns:
+            Dict[str, Any]: Dicionário com os resultados processados.
+        """
+        pass
+
+
+class StatisticsProcessor(Processor):
+    """
+    Implementação de referência que calcula estatísticas básicas.
+    Útil para testes e validação inicial.
+    """
+
+    def process(self, batch: np.ndarray) -> Dict[str, Any]:
+        return {
+            "mean": float(np.mean(batch)),
+            "std": float(np.std(batch)),
+            "min": float(np.min(batch)),
+            "max": float(np.max(batch)),
+        }

dataloom_engine/sinks.py

@@ -0,0 +1,172 @@
+# dataloom_engine/sinks.py
+
+"""
+Contratos de saída de dados (Sinks).
+Define como e onde os resultados processados são depositados.
+"""
+
+import csv
+import json
+import logging
+import queue
+import threading
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+from dataloom_engine.exceptions import LoomError
+
+logger = logging.getLogger(__name__)
+
+
+class Sink(ABC):
+    """Interface base para destinos de dados."""
+
+    @abstractmethod
+    def send(self, result: Dict[str, Any]) -> None:
+        """
+        Envia o resultado para o destino final.
+        Implementações devem garantir thread-safety se acessarem recursos compartilhados.
+        """
+        pass
+
+    def close(self) -> None:  # noqa: B027 -- no-op deliberado: close é opcional
+        """
+        Método de ciclo de vida chamado quando o Loom encerra.
+        Útil para fechar conexões, flushear buffers ou parar threads de background.
+        """
+        pass
+
+
+class JsonFileSink(Sink):
+    """
+    Sink padrão que escreve resultados em um arquivo JSON local.
+    Utiliza threading.Lock para garantir integridade na escrita concorrente.
+    """
+
+    def __init__(self, output_dir: Path):
+        self.output_dir = output_dir
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        # Lock garante que apenas um Weaver escreva no arquivo por vez
+        self._lock = threading.Lock()
+
+    def send(self, result: Dict[str, Any]) -> None:
+        filename = self.output_dir / "results.json"
+
+        with self._lock:
+            with open(filename, "a") as f:
+                json.dump(result, f)
+                f.write("\n")
+
+
+class CsvFileSink(Sink):
+    """
+    Sink que escreve resultados em um arquivo CSV local.
+
+    O cabeçalho é definido pelas chaves do primeiro resultado recebido.
+    Nos resultados seguintes, chaves extras são ignoradas e chaves
+    ausentes ficam vazias. Utiliza threading.Lock para garantir
+    integridade na escrita concorrente.
+    """
+
+    def __init__(self, output_dir: Path, filename: str = "results.csv"):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self._path = self.output_dir / filename
+        self._lock = threading.Lock()
+        self._fieldnames: Optional[list] = None
+
+    def send(self, result: Dict[str, Any]) -> None:
+        with self._lock:
+            fieldnames = self._fieldnames
+            write_header = fieldnames is None
+            if fieldnames is None:
+                fieldnames = list(result.keys())
+                self._fieldnames = fieldnames
+            with open(self._path, "a", newline="") as f:
+                writer = csv.DictWriter(f, fieldnames=fieldnames, extrasaction="ignore")
+                if write_header:
+                    writer.writeheader()
+                writer.writerow(result)
+
+
+class CallbackSink(Sink):
+    """
+    Sink que delega cada resultado a um callable fornecido pelo usuário.
+    Permite integrar o pipeline a qualquer destino (fila externa, banco,
+    métrica) sem precisar criar uma subclasse de Sink.
+
+    Atenção: o callable é invocado a partir das threads Weaver — deve
+    ser thread-safe.
+    """
+
+    def __init__(
+        self,
+        callback: Callable[[Dict[str, Any]], None],
+        on_close: Optional[Callable[[], None]] = None,
+    ):
+        self.callback = callback
+        self.on_close = on_close
+
+    def send(self, result: Dict[str, Any]) -> None:
+        self.callback(result)
+
+    def close(self) -> None:
+        if self.on_close is not None:
+            self.on_close()
+
+
+class ThreadedBufferedSink(Sink):
+    """
+    Decorator que adiciona um buffer em memória e escrita assíncrona
+    para qualquer Sink existente.
+
+    O worker consome a fila até encontrar o sentinela de parada, o que
+    garante que todos os itens enviados antes do close() sejam entregues
+    ao sink alvo, sem janelas de corrida entre sinalização e drenagem.
+    """
+
+    # Sentinela interno que instrui o worker a encerrar após drenar a fila
+    _STOP: Any = object()
+
+    def __init__(self, target_sink: Sink, buffer_size: int = 1000):
+        self.target = target_sink
+        self.queue: queue.Queue = queue.Queue(maxsize=buffer_size)
+        self._closed = False
+        self._close_lock = threading.Lock()
+        self.worker_thread = threading.Thread(target=self._worker, daemon=True)
+        self.worker_thread.start()
+
+    def send(self, result: Dict[str, Any]) -> None:
+        if self._closed:
+            raise LoomError("ThreadedBufferedSink já foi fechado; send() não é permitido.")
+        self.queue.put(result)
+
+    def _worker(self) -> None:
+        while True:
+            item = self.queue.get()
+            try:
+                if item is self._STOP:
+                    return
+                self.target.send(item)
+            except Exception:
+                # O worker precisa sobreviver a falhas do sink alvo,
+                # senão a fila para de drenar e o close() trava.
+                logger.exception("Sink alvo falhou ao receber item; item descartado.")
+            finally:
+                self.queue.task_done()
+
+    def close(self) -> None:
+        # Idempotente: apenas a primeira chamada executa o fechamento
+        with self._close_lock:
+            if self._closed:
+                return
+            self._closed = True
+
+        # O sentinela entra atrás dos itens pendentes: o worker drena
+        # tudo antes de encerrar
+        self.queue.put(self._STOP)
+        self.worker_thread.join()
+
+        # Propaga o fechamento
+        self.target.close()

dataloom_engine/sources.py

@@ -0,0 +1,56 @@
+# dataloom_engine/sources.py
+
+"""
+Data Sources Module.
+Defines the interface for generating or fetching data batches to be processed by the Loom.
+"""
+
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Iterator
+
+import numpy as np
+
+from dataloom_engine.config import LoomConfig
+
+
+class Source(ABC):
+    """
+    Abstract Base Class for data sources.
+    A Source must be iterable, yielding batches of data.
+    """
+
+    @abstractmethod
+    def __iter__(self) -> Iterator[Any]:
+        """
+        Yields data batches.
+        """
+        pass
+
+
+class RandomNumPySource(Source):
+    """
+    Standard source that generates random NumPy arrays.
+    Simulates a continuous data stream.
+    """
+
+    def __init__(self, config: LoomConfig, limit: int = -1):
+        """
+        Args:
+            config: Configuration object containing batch_size and interval_seconds.
+            limit: Maximum number of batches to generate. -1 for infinite.
+        """
+        self.config = config
+        self.limit = limit
+
+    def __iter__(self) -> Iterator[np.ndarray]:
+        count = 0
+        while self.limit == -1 or count < self.limit:
+            # Simulate generic production delay
+            time.sleep(self.config.interval_seconds)
+
+            # Generate batch
+            batch = np.random.rand(self.config.batch_size)
+            yield batch
+
+            count += 1

dataloom_engine/types.py

@@ -0,0 +1,18 @@
+# dataloom_engine/types.py
+
+"""
+Define os tipos fundamentais e estados do sistema DataLoom.
+Estas definições são usadas transversalmente por vários módulos para
+garantir consistência de estado.
+"""
+
+from enum import Enum
+
+
+class LoomState(Enum):
+    """Representa o estado atual do ciclo de vida da máquina Loom."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"

dataloom_engine/weaver.py

@@ -0,0 +1,84 @@
+# dataloom_engine/weaver.py
+
+"""
+Definição do Trabalhador (Weaver).
+Thread dedicada que consome tarefas da fila, processa e envia ao Sink.
+Este módulo é interno e não deve ser importado diretamente pelo usuário.
+"""
+
+import logging
+import queue
+import threading
+import time
+from typing import Any, Callable, Dict, Optional
+
+from dataloom_engine.exceptions import WeaverError
+from dataloom_engine.processors import Processor
+from dataloom_engine.sinks import Sink
+
+logger = logging.getLogger(__name__)
+
+# Sentinela interno: instrui o Weaver a encerrar. O Loom enfileira um
+# sentinela por Weaver após os dados, garantindo que a fila seja drenada
+# por completo antes das threads morrerem.
+STOP_SENTINEL: Any = object()
+
+
+class Weaver(threading.Thread):
+    """
+    Agente de execução que roda em uma thread separada.
+    Orquestra o fluxo: Fila -> Processor -> Sink.
+
+    Erros de processamento não matam a thread: são convertidos em
+    WeaverError, logados e reportados via callback on_error (se fornecido).
+    """
+
+    def __init__(
+        self,
+        task_queue: queue.Queue,
+        processor: Processor,
+        sink: Sink,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        on_batch_processed: Optional[Callable[[Dict[str, Any], float], None]] = None,
+    ):
+        super().__init__(daemon=True)
+        self.task_queue = task_queue
+        self.processor = processor
+        self.sink = sink
+        self.on_error = on_error
+        self.on_batch_processed = on_batch_processed
+
+    def run(self) -> None:
+        while True:
+            batch = self.task_queue.get()
+            try:
+                if batch is STOP_SENTINEL:
+                    return
+                self._process_batch(batch)
+            finally:
+                # Sinaliza que o item da fila foi tratado (sucesso ou falha)
+                self.task_queue.task_done()
+
+    def _process_batch(self, batch: Any) -> None:
+        try:
+            started = time.monotonic()
+            result = self.processor.process(batch)
+            self.sink.send(result)
+            duration = time.monotonic() - started
+        except Exception as exc:
+            logger.exception("Weaver falhou ao processar um lote; o lote foi descartado.")
+            if self.on_error is not None:
+                error = WeaverError(f"Falha ao processar lote: {exc}")
+                error.__cause__ = exc
+                try:
+                    self.on_error(error)
+                except Exception:
+                    logger.exception("Callback on_error lançou uma exceção.")
+            return
+
+        # Métrica só é emitida em sucesso; falhas passam pelo on_error
+        if self.on_batch_processed is not None:
+            try:
+                self.on_batch_processed(result, duration)
+            except Exception:
+                logger.exception("Callback on_batch_processed lançou uma exceção.")

dataloom_engine-0.3.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: dataloom-engine
+Version: 0.3.0
+Summary: DataLoom: Um orquestrador de threads leve e eficiente para dados.
+Author-email: Dioni Padilha <dionipdl@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dionipadilha/dataloom
+Project-URL: Changelog, https://github.com/dionipadilha/dataloom/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/dionipadilha/dataloom/issues
+Keywords: pipeline,data,threading,loom,concurrency
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# 🧵 DataLoom
+
+> Um motor de orquestração multi-thread leve, eficiente e seguro para Python.
+
+[![CI](https://github.com/dionipadilha/dataloom/actions/workflows/ci.yml/badge.svg)](https://github.com/dionipadilha/dataloom/actions/workflows/ci.yml) ![Python](https://img.shields.io/badge/python-3.9%2B-blue) ![License](https://img.shields.io/badge/license-MIT-green)
+
+<img width="2752" height="1536" alt="DataLoom: Um motor de orquestração multi-thread leve, eficiente e seguro para Python." src="https://github.com/user-attachments/assets/c1f3fc98-5eaf-4add-a38c-2717ae699cd5" />
+
+O **DataLoom** é uma biblioteca projetada para processar fluxos de dados utilizando o padrão **Produtor-Consumidor** com múltiplas threads (Weavers). Ele abstrai a complexidade de filas (`Queues`), sincronização (`Locks`) e gerenciamento de ciclo de vida, permitindo que você foque apenas na lógica de transformação dos dados.
+
+## Por que usar o DataLoom?
+⚡ Performance: Processamento paralelo real para tarefas I/O bound.
+🧩 Simplicidade: API intuitiva inspirada na metáfora de tecelagem.
+🛡️ Segurança: Thread-safety garantido por design em todo o pipeline.
+📦 Leve: Dependências mínimas, pronto para rodar em qualquer ambiente Python.
+
+### Por que não usar só `ThreadPoolExecutor`?
+
+Pergunta justa — a stdlib resolve o *paralelismo*, mas não o *pipeline*. O
+`concurrent.futures` te dá um pool de threads; tudo ao redor fica por sua conta:
+
+| Você precisa de...                                  | Com a stdlib             | Com o DataLoom                    |
+| --------------------------------------------------- | ------------------------ | --------------------------------- |
+| Fluxo contínuo produtor-consumidor                   | `Queue` + loops manuais  | `Loom` + `Source`                 |
+| Backpressure (produtor mais rápido que consumidores) | `Queue(maxsize=...)` manual | Padrão, configurável            |
+| Shutdown limpo (drenar fila, fechar recursos)        | Sentinelas e joins manuais | `stop()` / `with Loom(...)`     |
+| Worker que sobrevive a erros e os reporta            | try/except em cada worker | `hooks.on_error` centralizado    |
+| Métricas por item processado                         | Instrumentação manual    | `hooks.on_batch_processed`        |
+| Escrita concorrente segura em arquivo                | Lock manual              | Sinks prontos (JSON, CSV, callback) |
+
+Se o seu caso é "aplicar uma função a uma lista e coletar os resultados",
+use `ThreadPoolExecutor.map` — é a ferramenta certa. O DataLoom é para
+**fluxos contínuos ou longos** onde ciclo de vida, resiliência e
+observabilidade importam. E, como toda solução baseada em threads no
+CPython, o ganho de paralelismo vale para cargas **I/O bound**; para
+CPU bound, prefira multiprocessing.
+
+## ✨ Características
+
+- **API Coesa:** Conceitos alinhados (`Loom`, `Weaver`, `Sink`).
+- **Concorrente:** Gerencia automaticamente múltiplos _Weavers_ (threads) em paralelo.
+- **Seguro:** Sinks padrão são thread-safe e exceções são tipadas (`LoomError`).
+- **Resiliente:** Erros de processamento não derrubam os Weavers e são reportados via hooks.
+- **Gerenciável:** `Loom` é um context manager — `with Loom(...) as loom:` garante `stop()` automático.
+- **Backpressure:** Fila de tarefas limitada por padrão (`queue_maxsize`), evitando crescimento de memória sem controle.
+- **Observável:** Hooks de ciclo de vida e métricas por lote (`on_batch_processed` com resultado e duração), além de Logs integrados.
+
+## 📦 Instalação
+
+```bash
+pip install dataloom-engine
+```
+
+> ⚠️ **Atenção ao nome:** o pacote instala o módulo `dataloom_engine`
+> (`import dataloom_engine`). Não confunda com o pacote `dataloom` do PyPI,
+> que é um ORM de outro autor e não tem relação com este projeto.
+
+Para desenvolver ou usar a versão mais recente do repositório:
+
+```bash
+git clone https://github.com/dionipadilha/dataloom.git
+cd dataloom
+pip install -e .
+```
+
+## 🚀 Uso Rápido
+
+Aqui está um exemplo completo de como tecer um pipeline de dados:
+
+```python
+from pathlib import Path
+import numpy as np
+from dataloom_engine import (
+    Loom,
+    LoomConfig,
+    LoomLogs,
+    Processor,
+    JsonFileSink,
+    ThreadedBufferedSink
+)
+from dataloom_engine.sources import RandomNumPySource
+
+# 1. Defina sua lógica de processamento (Stateless)
+class MyFilterProcessor(Processor):
+    def process(self, batch: np.ndarray) -> dict:
+        # 'batch' é um array numpy com o tamanho definido na config
+        avg = float(batch.mean())
+        return {
+            "processed_items": len(batch),
+            "average_value": avg,
+            "status": "high" if avg > 0.5 else "low"
+        }
+
+# 2. Configuração Inicial
+if __name__ == "__main__":
+    # Configura logs no console
+    LoomLogs.setup()
+
+    # Define parâmetros do motor
+    config = LoomConfig(
+        output_dir=Path("./data_out"),
+        batch_size=100,      # Processa 100 itens por vez
+        interval_seconds=1   # Gera um novo lote a cada 1 segundo
+    )
+
+    # 3. Fonte de Dados
+    # Agora desvinculada do motor, permitindo fontes customizadas (DB, CSV, S3)
+    source = RandomNumPySource(config)
+
+    # 4. Sink Arquivado e Otimizado
+    # ThreadedBufferedSink evita que o I/O bloqueie o processamento
+    file_sink = JsonFileSink(config.output_dir)
+    sink = ThreadedBufferedSink(file_sink)
+
+    # 5. Inicializa o Loom (O Orquestrador)
+    loom = Loom(
+        config=config,
+        processor=MyFilterProcessor(),
+        sink=sink,
+        source=source,
+        num_weavers=4  # 4 Threads trabalhando em paralelo
+    )
+
+    print("🧵 DataLoom iniciado! Pressione Ctrl+C para parar.")
+    try:
+        # O context manager garante stop() e limpeza dos recursos,
+        # mesmo em caso de exceção ou Ctrl+C
+        with loom:
+            loom.start()
+    except KeyboardInterrupt:
+        print("\n🛑 Tear parado.")
+```
+
+## 🏗️ Arquitetura
+
+O DataLoom utiliza uma metáfora de tecelagem:
+
+- **Loom (Tear):** A máquina principal. Gerencia a fila de tarefas e o ciclo de vida.
+- **Weaver (Tecelão):** As threads trabalhadoras. Elas pegam a matéria-prima (batch), processam e entregam.
+- **Processor:** A lógica de negócio. Transforma dados brutos em informação.
+- **Sink:** O destino final. Onde o produto acabado é depositado (ex: `JsonFileSink`, `CsvFileSink`, ou qualquer destino via `CallbackSink`).
+
+## 🛠️ Desenvolvimento e Testes
+
+Para contribuir com o projeto ou rodar os testes unitários:
+
+1.  Instale as dependências de desenvolvimento:
+
+    ```bash
+    pip install -e ".[dev]"
+    ```
+
+2.  Rode a suíte de testes (via pytest):
+    ```bash
+    pytest
+    ```
+
+## 📄 Licença
+
+Este projeto está licenciado sob a licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
+
+## 🗒️ Histórico de versões
+
+As mudanças de cada versão estão documentadas no [CHANGELOG](CHANGELOG.md).

dataloom_engine-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+dataloom_engine/__init__.py,sha256=xiSTbVN-UNC2AgqXqmN_389W8oyFUY4pgWsPPWhkhic,1100
+dataloom_engine/config.py,sha256=617hDIdvFqZf-_5mMFLHYYUeE60dqFDKOtgn6c94HIA,1788
+dataloom_engine/exceptions.py,sha256=Vmwl4Us4uZrlggvVjZVNdsB__qeK4v3J5QrB2o7nvZ4,526
+dataloom_engine/hooks.py,sha256=wf4NeDB9tljrCWQ2Ws81E447ob56k3EVzZUerqNxrz4,1665
+dataloom_engine/logs.py,sha256=xo8LUl-8EVncmh7h3F6QaDt4byqN4trinrkbk0_QBl0,672
+dataloom_engine/loom.py,sha256=8d0rh25ScIgxndH2dKdIq6wg418gztuELotsZ9ozpYc,5450
+dataloom_engine/processors.py,sha256=Dh-AdkNsHS6q2dXDToqVbmfVCMuzwlw0cJhT4CBEpZw,1094
+dataloom_engine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dataloom_engine/sinks.py,sha256=n_JfwjnV63HQLZBOCzawbJBXtmKOteSzzSYzYV3rcrA,5629
+dataloom_engine/sources.py,sha256=CPth2KGSVCK7_r1UV3LDxMY-XZhZLOsRVTbt5A2KZAs,1385
+dataloom_engine/types.py,sha256=rsnKlTM5c_HbuWz4-_yq_l4-XGpPgpMuWn_Zp_Dn144,422
+dataloom_engine/weaver.py,sha256=k6WdgIr7P1rEGUfqF1NgkmJKiuK6gLXqJtMHiOT06NE,2909
+dataloom_engine-0.3.0.dist-info/licenses/LICENSE,sha256=Q0g4SFHxXcfz1o6yJa86DkY4QqnJzIXYCZJ1FiA-ivY,1072
+dataloom_engine-0.3.0.dist-info/METADATA,sha256=LB8Pj356mF00tclFD6qrz1Yt61NyOpvXrgB5g7_XKos,8284
+dataloom_engine-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+dataloom_engine-0.3.0.dist-info/top_level.txt,sha256=Zt-vsTb_3NRem8T-SVx5o8MolujisFvy8Y4Sfux7Q3E,16
+dataloom_engine-0.3.0.dist-info/RECORD,,

dataloom_engine-0.3.0.dist-info/WHEEL

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

dataloom_engine-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 [Dioni Padilha]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dataloom_engine-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dataloom_engine