jaylog 0.2.2__tar.gz → 0.2.5__tar.gz

{jaylog-0.2.2 → jaylog-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: jaylog
-Version: 0.2.2
+Version: 0.2.5
 Summary: Customized Python logging library with file rotation and HTTP forwarding
 Author: Gpocas
 Author-email: Gpocas <gpocas01@gmail.com>
@@ -34,11 +34,12 @@ As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do siste
 | Variável                        | obrigatório? | Padrão    | Descrição                                                               |
 | ------------------------------- | ------------ | --------- | ----------------------------------------------------------------------- |
 | `JAYLOG_APP_NAME`               | SIM          | `null`    | Nome do serviço/bot (usado no nome do arquivo de log)                   |
-| `JAYLOG_LOG_DIR`                | SIM          | `null`    | Caminho do diretório onde os arquivos de log serão salvos               |
+| `JAYLOG_LOG_DIR`                | NÃO          | `null`    | Caminho do diretório onde os arquivos de log serão salvos. Se omitido, o handler de arquivo é desativado |
 | `JAYLOG_LOG_LEVEL`              | NÃO          | `INFO`    | Nível mínimo de log (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)   |
 | `JAYLOG_LOG_MAX_BYTES`          | NÃO          | `5242880` | Tamanho máximo do arquivo de log antes de rotacionar (bytes)            |
 | `JAYLOG_LOG_BACKUP_COUNT`       | NÃO          | `5`       | Quantidade de arquivos de backup mantidos após rotação                  |
 | `JAYLOG_LOG_RETENTION_DAYS`     | NÃO          | `7`       | Dias para manter arquivos de log antigos                                |
+| `JAYLOG_LOG_CONSOLE_ENABLED`    | NÃO          | `true`    | Habilita saída colorida no console (`true`/`false`)                     |
 | `JAYLOG_LOG_HTTP_TIMEOUT`       | NÃO          | `5.0`     | Timeout em segundos para o envio HTTP                                   |
 | `JAYLOG_LOG_HTTP_ENDPOINT`      | NÃO          | `null`    | URL do endpoint que receberá os logs                                    |
 | `JAYLOG_LOG_HTTP_API_KEY`       | NÃO          | `null`    | Chave de autenticação enviada no header `x-api-key`                     |
@@ -48,6 +49,10 @@ As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do siste
 
 ## Como usar?
 
+> [!IMPORTANT]
+> A partir da versão 0.2.2, `configure()` **deve** ser chamado antes de `get_logger()`.
+> Chamar `get_logger()` sem configuração prévia lança uma exceção.
+
 Existem alguns cenários diferentes onde a utilização desse lib pode mudar, abaixo estão os cenários mapeados e como realizar configuração para cada um.
 
 ## Arquivo único
@@ -59,13 +64,34 @@ JAYLOG_LOG_DIR=C:\logs
 ```
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
-logger = get_logger(JaylogSettings())
+configure(JaylogSettings())
+
+logger = get_logger()
 
 logger.info("Arquivo Único")
 ```
 
+## Apenas console (sem arquivo de log)
+
+Basta omitir `JAYLOG_LOG_DIR`. O handler de console fica ativo por padrão.
+
+__*.env.logging*__
+```env
+JAYLOG_APP_NAME=meu-bot
+```
+__*main.py*__
+```python
+from jaylog import JaylogSettings, configure, get_logger
+
+configure(JaylogSettings())
+
+logger = get_logger()
+
+logger.info("Saída apenas no console")
+```
+
 ## Múltiplos Arquivos
 
 __*.env.logging*__
@@ -79,8 +105,7 @@ __*main.py*__
 from jaylog import JaylogSettings, get_logger, configure
 from parse import parse_csv
 
-jaylog_settings = JaylogSettings()
-configure(jaylog_settings)
+configure(JaylogSettings())
 
 logger = get_logger()
 
@@ -99,6 +124,31 @@ def parse_csv():
     logger.info("Múltiplos Arquivos - parse.py")
 ```
 
+## Múltiplos loggers nomeados
+
+Quando o projeto possui serviços distintos, passe uma lista para `configure()`. Cada entrada usa seu próprio `app_name` e grava em arquivos separados. O campo `[service]` é exibido automaticamente no formato do log quando há mais de um logger registrado.
+
+__*.env.logging*__
+```env
+JAYLOG_LOG_DIR=C:\logs
+```
+
+__*main.py*__
+```python
+from jaylog import JaylogSettings, configure, get_logger
+
+settings_order   = JaylogSettings(app_name="ORDER-PROCESSOR")
+settings_billing = JaylogSettings(app_name="BILLING")
+
+configure([settings_order, settings_billing])
+
+logger         = get_logger("ORDER-PROCESSOR")  # ou get_logger() — retorna o primeiro registrado
+billing_logger = get_logger("BILLING")
+
+logger.info("Pedido recebido")
+billing_logger.info("Fatura emitida")
+```
+
 
 
 ## Alterando Caminho padrão do .env
@@ -111,10 +161,10 @@ JAYLOG_LOG_DIR=C:\logs
 
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
-settings = JaylogSettings(_env_file='development.env')
-logger = get_logger(settings)
+configure(JaylogSettings(_env_file='development.env'))
+logger = get_logger()
 
 logger.info("Alterando Caminho padrão do .env")
 ```
@@ -152,13 +202,13 @@ JAYLOG_LOG_HTTP_PROXY
 
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
-settings = JaylogSettings(
+configure(JaylogSettings(
     _env_file='prodution.env',
     _secrets_dir='/foo/bar/secrets/'
-)
-logger = get_logger(settings)
+))
+logger = get_logger()
 
 logger.info("Mensagem de log")
 ```
@@ -174,12 +224,11 @@ JAYLOG_SECRETS_DIR=/foo/bar/secrets
 
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
 # nesse caso é necessário usar a função de classe `reload_secrets`
 # pois o diretorio dos secrets foi passado via variável de ambiente
-settings = JaylogSettings(_env_file='prodution.env').reload_secrets() 
-
-logger = get_logger(settings)
+configure(JaylogSettings(_env_file='prodution.env').reload_secrets())
+logger = get_logger()
 
 logger.info("Mensagem de log")

{jaylog-0.2.2 → jaylog-0.2.5}/README.md

@@ -15,11 +15,12 @@ As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do siste
 | Variável                        | obrigatório? | Padrão    | Descrição                                                               |
 | ------------------------------- | ------------ | --------- | ----------------------------------------------------------------------- |
 | `JAYLOG_APP_NAME`               | SIM          | `null`    | Nome do serviço/bot (usado no nome do arquivo de log)                   |
-| `JAYLOG_LOG_DIR`                | SIM          | `null`    | Caminho do diretório onde os arquivos de log serão salvos               |
+| `JAYLOG_LOG_DIR`                | NÃO          | `null`    | Caminho do diretório onde os arquivos de log serão salvos. Se omitido, o handler de arquivo é desativado |
 | `JAYLOG_LOG_LEVEL`              | NÃO          | `INFO`    | Nível mínimo de log (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)   |
 | `JAYLOG_LOG_MAX_BYTES`          | NÃO          | `5242880` | Tamanho máximo do arquivo de log antes de rotacionar (bytes)            |
 | `JAYLOG_LOG_BACKUP_COUNT`       | NÃO          | `5`       | Quantidade de arquivos de backup mantidos após rotação                  |
 | `JAYLOG_LOG_RETENTION_DAYS`     | NÃO          | `7`       | Dias para manter arquivos de log antigos                                |
+| `JAYLOG_LOG_CONSOLE_ENABLED`    | NÃO          | `true`    | Habilita saída colorida no console (`true`/`false`)                     |
 | `JAYLOG_LOG_HTTP_TIMEOUT`       | NÃO          | `5.0`     | Timeout em segundos para o envio HTTP                                   |
 | `JAYLOG_LOG_HTTP_ENDPOINT`      | NÃO          | `null`    | URL do endpoint que receberá os logs                                    |
 | `JAYLOG_LOG_HTTP_API_KEY`       | NÃO          | `null`    | Chave de autenticação enviada no header `x-api-key`                     |
@@ -29,6 +30,10 @@ As variáveis usam o prefixo `JAYLOG_`. Podem ser definidas no ambiente do siste
 
 ## Como usar?
 
+> [!IMPORTANT]
+> A partir da versão 0.2.2, `configure()` **deve** ser chamado antes de `get_logger()`.
+> Chamar `get_logger()` sem configuração prévia lança uma exceção.
+
 Existem alguns cenários diferentes onde a utilização desse lib pode mudar, abaixo estão os cenários mapeados e como realizar configuração para cada um.
 
 ## Arquivo único
@@ -40,13 +45,34 @@ JAYLOG_LOG_DIR=C:\logs
 ```
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
-logger = get_logger(JaylogSettings())
+configure(JaylogSettings())
+
+logger = get_logger()
 
 logger.info("Arquivo Único")
 ```
 
+## Apenas console (sem arquivo de log)
+
+Basta omitir `JAYLOG_LOG_DIR`. O handler de console fica ativo por padrão.
+
+__*.env.logging*__
+```env
+JAYLOG_APP_NAME=meu-bot
+```
+__*main.py*__
+```python
+from jaylog import JaylogSettings, configure, get_logger
+
+configure(JaylogSettings())
+
+logger = get_logger()
+
+logger.info("Saída apenas no console")
+```
+
 ## Múltiplos Arquivos
 
 __*.env.logging*__
@@ -60,8 +86,7 @@ __*main.py*__
 from jaylog import JaylogSettings, get_logger, configure
 from parse import parse_csv
 
-jaylog_settings = JaylogSettings()
-configure(jaylog_settings)
+configure(JaylogSettings())
 
 logger = get_logger()
 
@@ -80,6 +105,31 @@ def parse_csv():
     logger.info("Múltiplos Arquivos - parse.py")
 ```
 
+## Múltiplos loggers nomeados
+
+Quando o projeto possui serviços distintos, passe uma lista para `configure()`. Cada entrada usa seu próprio `app_name` e grava em arquivos separados. O campo `[service]` é exibido automaticamente no formato do log quando há mais de um logger registrado.
+
+__*.env.logging*__
+```env
+JAYLOG_LOG_DIR=C:\logs
+```
+
+__*main.py*__
+```python
+from jaylog import JaylogSettings, configure, get_logger
+
+settings_order   = JaylogSettings(app_name="ORDER-PROCESSOR")
+settings_billing = JaylogSettings(app_name="BILLING")
+
+configure([settings_order, settings_billing])
+
+logger         = get_logger("ORDER-PROCESSOR")  # ou get_logger() — retorna o primeiro registrado
+billing_logger = get_logger("BILLING")
+
+logger.info("Pedido recebido")
+billing_logger.info("Fatura emitida")
+```
+
 
 
 ## Alterando Caminho padrão do .env
@@ -92,10 +142,10 @@ JAYLOG_LOG_DIR=C:\logs
 
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
-settings = JaylogSettings(_env_file='development.env')
-logger = get_logger(settings)
+configure(JaylogSettings(_env_file='development.env'))
+logger = get_logger()
 
 logger.info("Alterando Caminho padrão do .env")
 ```
@@ -133,13 +183,13 @@ JAYLOG_LOG_HTTP_PROXY
 
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
-settings = JaylogSettings(
+configure(JaylogSettings(
     _env_file='prodution.env',
     _secrets_dir='/foo/bar/secrets/'
-)
-logger = get_logger(settings)
+))
+logger = get_logger()
 
 logger.info("Mensagem de log")
 ```
@@ -155,12 +205,11 @@ JAYLOG_SECRETS_DIR=/foo/bar/secrets
 
 __*main.py*__
 ```python
-from jaylog import JaylogSettings, get_logger
+from jaylog import JaylogSettings, configure, get_logger
 
 # nesse caso é necessário usar a função de classe `reload_secrets`
 # pois o diretorio dos secrets foi passado via variável de ambiente
-settings = JaylogSettings(_env_file='prodution.env').reload_secrets() 
-
-logger = get_logger(settings)
+configure(JaylogSettings(_env_file='prodution.env').reload_secrets())
+logger = get_logger()
 
 logger.info("Mensagem de log")

{jaylog-0.2.2 → jaylog-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jaylog"
-version = "0.2.2"
+version = "0.2.5"
 description = "Customized Python logging library with file rotation and HTTP forwarding"
 readme = "README.md"
 authors = [

{jaylog-0.2.2 → jaylog-0.2.5}/src/jaylog/formatters.py

@@ -100,11 +100,18 @@ def build_log_entry_dict(record: logging.LogRecord) -> dict:
 class PlainTextFormatter(logging.Formatter):
     """Human-readable single-line formatter for .log files."""
 
+    def __init__(self, show_service: bool = True) -> None:
+        super().__init__()
+        self.show_service = show_service
+
     def format(self, record: logging.LogRecord) -> str:
         entry = build_log_entry_dict(record)
-        line = (
-            f"{entry['log_timestamp']} [{entry['log_level']}]"
-            f" {entry['service']} {entry['hostname']}({entry['ipv4']}) {entry['username']}"
-            f" | {entry['log_message']}"
+        log_timestamp = datetime.fromisoformat(entry['log_timestamp']).astimezone().strftime('%d/%m/%Y %X')
+        log_level = f'[{entry["log_level"]}]'
+        service_segment = f'[{entry["service"]}] | ' if self.show_service else ''
+        return (
+            f'{log_timestamp} '
+            f'{log_level.ljust(11)} | '
+            f'{service_segment}'
+            f"{entry['log_message']}"
         )
-        return line

jaylog-0.2.5/src/jaylog/handlers/__init__.py

@@ -0,0 +1,5 @@
+from .console_handler import JaylogConsoleHandler
+from .file_handler import JaylogFileHandler
+from .http_handler import JaylogHttpHandler
+
+__all__ = ["JaylogConsoleHandler", "JaylogFileHandler", "JaylogHttpHandler"]

jaylog-0.2.5/src/jaylog/handlers/console_handler.py

@@ -0,0 +1,43 @@
+import logging
+import sys
+from datetime import datetime
+
+from jaylog.formatters import build_log_entry_dict
+
+_GREEN = "\033[32m"
+_BLUE = "\033[34m"
+_PURPLE = "\033[35m"
+_YELLOW = "\033[33m"
+_RED = "\033[31m"
+_RESET = "\033[0m"
+
+_LEVEL_COLORS = {
+    "DEBUG": _PURPLE,
+    "INFO": _BLUE,
+    "WARNING": _YELLOW,
+}
+
+
+def _level_color(level: str) -> str:
+    return _LEVEL_COLORS.get(level, _RED)
+
+
+class ConsoleFormatter(logging.Formatter):
+    def __init__(self, show_service: bool = True) -> None:
+        super().__init__()
+        self.show_service = show_service
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry = build_log_entry_dict(record)
+        log_timestamp = datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
+        log_level = f'[{entry["log_level"]}]'
+        colored_timestamp = f"{_GREEN}{log_timestamp}{_RESET}"
+        colored_level = f"{_level_color(entry['log_level'])}{log_level.ljust(11)}{_RESET}"
+        service_segment = f'[{entry["service"]}] | ' if self.show_service else ''
+        return f"{colored_timestamp} {colored_level} | {service_segment}{entry['log_message']}"
+
+
+class JaylogConsoleHandler(logging.StreamHandler):
+    def __init__(self, show_service: bool = True) -> None:
+        super().__init__(stream=sys.stdout)
+        self.setFormatter(ConsoleFormatter(show_service=show_service))

{jaylog-0.2.2 → jaylog-0.2.5}/src/jaylog/handlers/file_handler.py

@@ -19,6 +19,7 @@ class JaylogFileHandler(RotatingFileHandler):
         backup_count: int = 20,
         retention_days: int = 7,
         encoding: str = "utf-8",
+        show_service: bool = True,
     ) -> None:
         filename.parent.mkdir(parents=True, exist_ok=True)
         super().__init__(
@@ -28,7 +29,7 @@ class JaylogFileHandler(RotatingFileHandler):
             encoding=encoding,
         )
         self.retention_days = retention_days
-        self.setFormatter(PlainTextFormatter())
+        self.setFormatter(PlainTextFormatter(show_service=show_service))
 
     def doRollover(self) -> None:
         super().doRollover()

{jaylog-0.2.2 → jaylog-0.2.5}/src/jaylog/logger.py

@@ -6,6 +6,7 @@ from queue import Queue
 
 from jaylog.filters import ExceptionFlagFilter
 from jaylog.formatters import configure_screenshot
+from jaylog.handlers.console_handler import JaylogConsoleHandler
 from jaylog.handlers.file_handler import JaylogFileHandler
 from jaylog.handlers.http_handler import JaylogHttpHandler
 from jaylog.settings import JaylogSettings
@@ -105,16 +106,24 @@ def get_logger(name: str | None = None) -> logging.Logger:
     # Build the actual (downstream) handlers
     # ------------------------------------------------------------------
     downstream: list[logging.Handler] = []
+    show_service = len(_settings_registry) > 1
+
+    if settings.log_dir is not None:
+        log_path = settings.log_dir / settings.log_filename
+        file_handler = JaylogFileHandler(
+            filename=log_path,
+            max_bytes=settings.log_max_bytes,
+            backup_count=settings.log_backup_count,
+            retention_days=settings.log_retention_days,
+            show_service=show_service,
+        )
+        file_handler.setLevel(settings.log_level)
+        downstream.append(file_handler)
 
-    log_path = settings.log_dir / settings.log_filename
-    file_handler = JaylogFileHandler(
-        filename=log_path,
-        max_bytes=settings.log_max_bytes,
-        backup_count=settings.log_backup_count,
-        retention_days=settings.log_retention_days,
-    )
-    file_handler.setLevel(settings.log_level)
-    downstream.append(file_handler)
+    if settings.log_console_enabled:
+        console_handler = JaylogConsoleHandler(show_service=show_service)
+        console_handler.setLevel(settings.log_level)
+        downstream.append(console_handler)
 
     if settings.log_http_endpoint and settings.log_http_api_key:
         http_handler = JaylogHttpHandler(

{jaylog-0.2.2 → jaylog-0.2.5}/src/jaylog/settings.py

@@ -31,7 +31,7 @@ class JaylogSettings(BaseSettings):
 
     # App identity
     app_name: str
-    log_dir: Path
+    log_dir: Path | None = None
 
     secrets_dir: Path | None = None
 
@@ -47,19 +47,24 @@ class JaylogSettings(BaseSettings):
     log_http_timeout: float = 5.0
     log_http_proxy: Optional[str] = None
 
+    # Console handler — desativar com JAYLOG_LOG_CONSOLE_ENABLED=false
+    log_console_enabled: bool = True
+
     # Screenshot (log_img field) — desativar com JAYLOG_LOG_SCREENSHOT_ENABLED=false
     log_screenshot_enabled: bool = False
 
     @field_validator("log_dir", mode="after")
     @classmethod
-    def validate_log_dir(cls, v: Path) -> Path:
-        if v.exists() and not v.is_dir():
+    def validate_log_dir(cls, v: Path | None) -> Path | None:
+        if v is not None and v.exists() and not v.is_dir():
             raise ValueError(f"JAYLOG_LOG_DIR '{v}' exists but is not a directory")
         return v
 
     @computed_field
     @property
-    def log_filename(self) -> Path:
+    def log_filename(self) -> Path | None:
+        if self.log_dir is None:
+            return None
         return Path(f"{self.app_name}_{_HOSTNAME}_{_HOST_USERNAME}.log")
 
     def reload_secrets(self):

jaylog-0.2.2/src/jaylog/handlers/__init__.py

@@ -1,4 +0,0 @@
-from .file_handler import JaylogFileHandler
-from .http_handler import JaylogHttpHandler
-
-__all__ = ["JaylogFileHandler", "JaylogHttpHandler"]