jaylog 0.2.4__tar.gz → 0.2.6__tar.gz

{jaylog-0.2.4 → jaylog-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: jaylog
-Version: 0.2.4
+Version: 0.2.6
 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.4 → jaylog-0.2.6}/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.4 → jaylog-0.2.6}/pyproject.toml

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

{jaylog-0.2.4 → jaylog-0.2.6}/src/jaylog/formatters.py

@@ -93,6 +93,7 @@ def build_log_entry_dict(record: logging.LogRecord) -> dict:
         "hostname": _HOSTNAME,
         "ipv4": _HOST_IP,
         "service_path": record.pathname,
+        "line_number": record.lineno,
         "log_img": _capture_screenshot() if (record.levelno >= logging.ERROR or is_exception) else None,
     }
 
@@ -106,7 +107,7 @@ class PlainTextFormatter(logging.Formatter):
 
     def format(self, record: logging.LogRecord) -> str:
         entry = build_log_entry_dict(record)
-        log_timestamp = datetime.fromisoformat(entry['log_timestamp']).strftime('%d/%m/%Y %X')
+        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 (

{jaylog-0.2.4 → jaylog-0.2.6}/src/jaylog/handlers/console_handler.py

@@ -29,7 +29,7 @@ class ConsoleFormatter(logging.Formatter):
 
     def format(self, record: logging.LogRecord) -> str:
         entry = build_log_entry_dict(record)
-        log_timestamp = datetime.fromisoformat(entry["log_timestamp"]).strftime("%d/%m/%Y %X")
+        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}"

{jaylog-0.2.4 → jaylog-0.2.6}/src/jaylog/handlers/http_handler.py

@@ -50,7 +50,7 @@ class JaylogHttpHandler(logging.Handler):
         super().__init__()
         self.endpoint = endpoint
         self.timeout = timeout
-        self.proxy = {'http': proxy, 'https': proxy}
+        self.proxy = {'http': proxy, 'https': proxy} if proxy else None
         self._session = requests.Session()
         self._session.headers["x-api-key"] = api_key
         self._session.headers["x-jaylog-version"] = _JAYLOG_VERSION

{jaylog-0.2.4 → jaylog-0.2.6}/src/jaylog/logger.py

@@ -3,6 +3,7 @@ import logging
 import signal
 from logging.handlers import QueueHandler, QueueListener
 from queue import Queue
+from typing import cast
 
 from jaylog.filters import ExceptionFlagFilter
 from jaylog.formatters import configure_screenshot
@@ -74,12 +75,26 @@ def get_logger(name: str | None = None) -> logging.Logger:
     configuração registrada. Chamadas repetidas com o mesmo nome retornam o
     **mesmo** logger, sem re-anexar handlers.
 
+    Se ``configure()`` ainda não tiver sido chamado, retorna um proxy
+    preguiçoso: nenhum erro é levantado aqui. O erro só aparece no primeiro
+    uso efetivo (``logger.info(...)``, ``logger.warning(...)`` etc.), o que
+    permite fazer ``logger = get_logger()`` no topo de um módulo antes de
+    ``configure()`` ter rodado em outro lugar.
+
     Architecture:
         logger  →  QueueHandler  →  Queue  →  QueueListener  →  [FileHandler, HttpHandler?]
 
     The QueueListener runs in a background thread so `emit()` never blocks the
     calling thread.
     """
+    if not _settings_registry:
+        # _LazyLogger não é um logging.Logger de verdade: é um proxy que
+        # delega (via __getattr__) para o logger real assim que ele existir.
+        return cast(logging.Logger, _LazyLogger(name))
+    return _build_logger(name)
+
+
+def _build_logger(name: str | None) -> logging.Logger:
     if not _settings_registry:
         raise Exception(
             'Não é possivel retornar uma instancia de logger sem configuração\n'
@@ -109,6 +124,7 @@ def get_logger(name: str | None = None) -> logging.Logger:
     show_service = len(_settings_registry) > 1
 
     if settings.log_dir is not None:
+        assert settings.log_filename is not None
         log_path = settings.log_dir / settings.log_filename
         file_handler = JaylogFileHandler(
             filename=log_path,
@@ -158,6 +174,27 @@ def get_logger(name: str | None = None) -> logging.Logger:
     return logger
 
 
+class _LazyLogger:
+    """
+    Proxy devolvido por ``get_logger()`` quando ``configure()`` ainda não
+    rodou. Resolve o logger real (e levanta o erro de configuração ausente,
+    se for o caso) apenas no primeiro atributo acessado — ou seja, na
+    primeira chamada de ``.info()``, ``.warning()`` etc.
+    """
+
+    def __init__(self, name: str | None) -> None:
+        self._name = name
+        self._resolved: logging.Logger | None = None
+
+    def _resolve(self) -> logging.Logger:
+        if self._resolved is None:
+            self._resolved = _build_logger(self._name)
+        return self._resolved
+
+    def __getattr__(self, item):
+        return getattr(self._resolve(), item)
+
+
 def shutdown(name: str | None = None) -> None:
     """
     Stop the QueueListener(s) gracefully, flushing any remaining records.

{jaylog-0.2.4 → jaylog-0.2.6}/src/jaylog/models.py

@@ -13,4 +13,5 @@ class LogEntry(BaseModel):
     hostname: str
     ipv4: str
     service_path: str
+    line_number: int
     log_img: Optional[str] = None