lbxtoolkit 2.0.4__tar.gz → 2.0.5__tar.gz

{lbxtoolkit-2.0.4 → lbxtoolkit-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lbxtoolkit
-Version: 2.0.4
+Version: 2.0.5
 Summary: Biblioteca de ferramentas LBX S/A
 Author: Cristiano P. Ferrari
 Author-email: boxferrari@gmail.com
@@ -52,6 +52,7 @@ Esta biblioteca possui ferramentas de uso recorrente para interação com banco
   - _.print_:            Contorna o manipulador de log e imprime diretamente na tela (stdout), sem formatar a mensagem nem registrar no arquivo
   - _.debug, .info, .aviso, .erro, .critico_:  Classifica as mensagens por nível de severidade/relevância e rediciona a saída (arquivo, tela, tela+arquivo) conforme a configuração do nível
   - _.stop_logging_:   Interrompe a manipulação das saídas pelo logger e restaura as saídas padrão (stdout/stderr) para a tela 
+  - _.filtra_:          Filtra os eventos do arquivo de log registrados em um intervalo de tempo específico
 
 **misc**:                 Classe de miscelâneas/diversos
   - _.seleciona_arquivo_: Abre um picker do sistema operacionar para selecionar um *arquivo* e retorna seu path
@@ -321,7 +322,7 @@ Para uso em APIs com autenticação JWT (JSON Web Token), OAuth, Bearer Token Au
 
 #### Classe **lbx_logger**
 
-Essa classe tem o propósito de manipular e formatar as mensagens de saída do script, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
+Essa classe requer a importação do módulo `logging` no script em que for instanciada e tem o propósito de manipular/formatar as mensagens de saída do script, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
 
 O comportamento padrão é registrar todas as saídas *simultaneamente* em tela e no arquivo com endereço informado no parâmetro `log_file_path`. Se este parametro for omisso no instanciamento da classe, as mensagens serão exibidas apenas na tela.
 
@@ -349,7 +350,7 @@ Os parametros para o instanciamento da classe são:
 - `ignore_console` Lista com os níveis de severidade a serem ignorados para *apresentação na tela*, registrando *apenas no arquivo* (quando informado no parametro `log_file_path`) e obedecendo ao nível mínimo estabelecido no parametro `log_level`. Note que omitir o parametro `log_file_path` e incluir um nível na lsita `ignore_console` implica em ignorar/suprimir esse nível de mensagem de qualquer apresentação.
 - `ignore_file` Mesma lógica do parametro `ignore_console`, mas com lógica invertida: suprime o registro do nível do arquivo e demonstra *apenas na tela*.
 
-As mensagem são manipuladas substituindo-se o comando `print()` pela chamada a um dos 5 métodos acima (_.add(), .debug(), .info(), .aviso(), .erro(), .critico()_). Exceto o método `.add()`, qualquer um dos demais métodos pode interromper a execução do script, através da passagem do parâmetro `exit`. Ao informar esse parametro na chamadada do método, atribua a ele o código de saída desejado (0 para normal, qualquer outro número para saída com erro). Exemplo:
+1) As mensagem são manipuladas substituindo-se o comando `print()` pela chamada a um dos 5 métodos acima (_.add(), .debug(), .info(), .aviso(), .erro(), .critico()_). Exceto o método `.add()`, qualquer um dos demais métodos pode interromper a execução do script, através da passagem do parâmetro `exit`. Ao informar esse parametro na chamadada do método, atribua a ele o código de saída desejado (0 para normal, qualquer outro número para saída com erro). Exemplo:
 
 ```
 log.erro('Essa mensagem apenas resulta em uma mensagem de nível ERROR')
@@ -359,7 +360,7 @@ log.erro('Essa mensagem resulta em uma mensagem de nível ERRO e encerra o scrip
 Qualquer chamada ao comando `print()`, uma vez instanciado manipulador de log, será registada como uma chamada ao método _.info()_ e registrada com este nível de severidade. 
 Para retornar ao comportamente padrão do comando print, ou interromper o manipulador, faça chamada ao método `.stop_logging()`
 
-O método _.add()_ não exibe/grava imediatamente a mensagem, mas apenas a diciona a _buffer_. Todas as chamas a _.add()_ irão concatenar a mensagem recebida até a próxima chamada em algum dos níveis _.debug(), .info(), .aviso(), .erro(), .critico()_. Na primeira chama de um destes níveis após uma (ou mais) chamada(s) ao método _.add()_ o *buffer* será concatenado à mensagem recebida por um destes métodos e o resultado será manipulado pelo log conforme os parametros definidos no intanciamento da classe e o método chamado. Essa função é útil para tratar mensagens com retorno condicional. Exemplo:
+2) O método _.add()_ não exibe/grava imediatamente a mensagem, mas apenas a diciona a _buffer_. Todas as chamas a _.add()_ irão concatenar a mensagem recebida até a próxima chamada em algum dos níveis _.debug(), .info(), .aviso(), .erro(), .critico()_. Na primeira chama de um destes níveis após uma (ou mais) chamada(s) ao método _.add()_ o *buffer* será concatenado à mensagem recebida por um destes métodos e o resultado será manipulado pelo log conforme os parametros definidos no intanciamento da classe e o método chamado. Essa função é útil para tratar mensagens com retorno condicional. Exemplo:
 
 ```
 log.add('Mensagem 1# ') ## não será exibida/registrada
@@ -367,15 +368,26 @@ log.add('Mensagem 2# ') ## não será exibida/registrada
 log.info('Mensagem 3) ## será exibida/registrada como nível "info" e com texto: "Mensagem 1# Mensagem 2# Mensagem 3"
 ```
 
-Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: ``message``, `corte=None`, `exit=None`.
+3) Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: `message`, `corte=None`, `exit=None`.
 
  - `message`: posicional e obrigatório. corresponde à mensagem a ser exibida
  - `corte`: o tamanho máximo da mensagem a ser exibida. opcional e se omitido, exibe a mensagem inteira. se fornecido, corta a mensagem no comprimento informado
  - `exit`: opcional. se informado (requer um código de retorno), aborta o script com o código informado. se omisso (padrão) a mensagem apenas é minutada pelo log, sem interferir no funcionamento do script
 
-Essa classe requer a importação do módulo `logging` no script em que for instanciada.
+4) O método `.filtra()` possui 3 parametros posicionais, todos opcionais: `log_file`, `dh_ini`, `dh_fim`.
 
-Exemplos de uso:
+Se os 3 forem omitidos, serão exibidas as entradas de log do arquivo corrente, definido no instanciamento da classe `lbx_logger`, registradas na última hora. Deste modo, o valor padrão para `dh_fim` é `now()`  e para `dh_ini` é `now()` menos 1 hora.
+
+Caso queira filtrar os registro de outro arquivo de log, que não seja o do script corrente, informe o endereço do arquivo no primeiro parametro.
+
+E caso queira alterar alterar o período de filtragem, informe nos parametros 2 e 3 a data/hora de início e fim do período. Estes dois parametros aceitam tanto um objeto do tipo `datetime` como uma string (que será convertida para datetime), desde que ela esteja no formato `dd/mm/aaaa hh:mm:[ss]` (segundos são opcionais).
+
+Considerando que os parametros são posicionais, caso queira omitir apenas um dos parametros, preencha a posição do parametro a ser omitido com `None`.
+
+A saída dessa função retorna um objeto, que pode ser salvo em disco ou impresso na tela.
+
+
+5) Exemplos de uso:
 
 ```
 from lbx_toolkit import lbx_logger 
@@ -417,6 +429,34 @@ except Exception as e:
 log.erro('Essa é uma mensagem de erro e abortará a execução do script', exit=1)
 
 log.info('Essa mensagem não será exibida pois o script foi abortado na mensagem anterior')
+
+# obtem os registros de log da última hora (comportamento padrão)
+filtra_log = log.search() 
+
+# obtem os registros das últimas 6 horas
+ultimas_6h = datetime.datetime.now() - datetime.timedelta(hours=6) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
+filtra_log = log.search(None, ultimas_6h) # None no 1º parametro impõe o log do arquivo corrente como padrão (definido em 'LogFile' e apontado no instanciamento da classe)
+
+# obtem os registros do dia 14/01/2020 até 3h atrás
+ultimas_3h = datetime.datetime.now() - datetime.timedelta(hours=3) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
+filtra_log = log.search(None, '14/01/2020 00:00', ultimas_3h) # 
+
+# obtem os registros do horário comercial do dia 23/12/2023 do arquivo salvo em C:\temp\outro_arquivo.log
+Outro_Log = Path(r'c:\temp\outro_arquivo.log')
+filtra_log = log.search(Outro_Log, '23/12/2023 08:00', '23/12/2023 18:00') # 
+
+# salva conteúdo filtrado em um arquivo:
+filtrado = 'filtered_log.txt'
+with open(filtado, 'w', encoding='ISO-8859-1') as output_file:  # indique o enconding conforme salvo (UTF-8 ou ISO-8859-1)
+    output_file.writelines(filta_log)    
+
+# mostra o conteúdo filtrado na tela
+print(''.join(filtra_log))
+
+# mostra o conteúdo filtrado na tela, listando apenas as os registros do nível "DEBUG"
+for line in filtered_lines:
+    if "DEBUG" in line:
+        print(line, end='')
 ```
 
 #### Classe **misc**

{lbxtoolkit-2.0.4 → lbxtoolkit-2.0.5}/README.md

@@ -29,6 +29,7 @@ Esta biblioteca possui ferramentas de uso recorrente para interação com banco
   - _.print_:            Contorna o manipulador de log e imprime diretamente na tela (stdout), sem formatar a mensagem nem registrar no arquivo
   - _.debug, .info, .aviso, .erro, .critico_:  Classifica as mensagens por nível de severidade/relevância e rediciona a saída (arquivo, tela, tela+arquivo) conforme a configuração do nível
   - _.stop_logging_:   Interrompe a manipulação das saídas pelo logger e restaura as saídas padrão (stdout/stderr) para a tela 
+  - _.filtra_:          Filtra os eventos do arquivo de log registrados em um intervalo de tempo específico
 
 **misc**:                 Classe de miscelâneas/diversos
   - _.seleciona_arquivo_: Abre um picker do sistema operacionar para selecionar um *arquivo* e retorna seu path
@@ -298,7 +299,7 @@ Para uso em APIs com autenticação JWT (JSON Web Token), OAuth, Bearer Token Au
 
 #### Classe **lbx_logger**
 
-Essa classe tem o propósito de manipular e formatar as mensagens de saída do script, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
+Essa classe requer a importação do módulo `logging` no script em que for instanciada e tem o propósito de manipular/formatar as mensagens de saída do script, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
 
 O comportamento padrão é registrar todas as saídas *simultaneamente* em tela e no arquivo com endereço informado no parâmetro `log_file_path`. Se este parametro for omisso no instanciamento da classe, as mensagens serão exibidas apenas na tela.
 
@@ -326,7 +327,7 @@ Os parametros para o instanciamento da classe são:
 - `ignore_console` Lista com os níveis de severidade a serem ignorados para *apresentação na tela*, registrando *apenas no arquivo* (quando informado no parametro `log_file_path`) e obedecendo ao nível mínimo estabelecido no parametro `log_level`. Note que omitir o parametro `log_file_path` e incluir um nível na lsita `ignore_console` implica em ignorar/suprimir esse nível de mensagem de qualquer apresentação.
 - `ignore_file` Mesma lógica do parametro `ignore_console`, mas com lógica invertida: suprime o registro do nível do arquivo e demonstra *apenas na tela*.
 
-As mensagem são manipuladas substituindo-se o comando `print()` pela chamada a um dos 5 métodos acima (_.add(), .debug(), .info(), .aviso(), .erro(), .critico()_). Exceto o método `.add()`, qualquer um dos demais métodos pode interromper a execução do script, através da passagem do parâmetro `exit`. Ao informar esse parametro na chamadada do método, atribua a ele o código de saída desejado (0 para normal, qualquer outro número para saída com erro). Exemplo:
+1) As mensagem são manipuladas substituindo-se o comando `print()` pela chamada a um dos 5 métodos acima (_.add(), .debug(), .info(), .aviso(), .erro(), .critico()_). Exceto o método `.add()`, qualquer um dos demais métodos pode interromper a execução do script, através da passagem do parâmetro `exit`. Ao informar esse parametro na chamadada do método, atribua a ele o código de saída desejado (0 para normal, qualquer outro número para saída com erro). Exemplo:
 
 ```
 log.erro('Essa mensagem apenas resulta em uma mensagem de nível ERROR')
@@ -336,7 +337,7 @@ log.erro('Essa mensagem resulta em uma mensagem de nível ERRO e encerra o scrip
 Qualquer chamada ao comando `print()`, uma vez instanciado manipulador de log, será registada como uma chamada ao método _.info()_ e registrada com este nível de severidade. 
 Para retornar ao comportamente padrão do comando print, ou interromper o manipulador, faça chamada ao método `.stop_logging()`
 
-O método _.add()_ não exibe/grava imediatamente a mensagem, mas apenas a diciona a _buffer_. Todas as chamas a _.add()_ irão concatenar a mensagem recebida até a próxima chamada em algum dos níveis _.debug(), .info(), .aviso(), .erro(), .critico()_. Na primeira chama de um destes níveis após uma (ou mais) chamada(s) ao método _.add()_ o *buffer* será concatenado à mensagem recebida por um destes métodos e o resultado será manipulado pelo log conforme os parametros definidos no intanciamento da classe e o método chamado. Essa função é útil para tratar mensagens com retorno condicional. Exemplo:
+2) O método _.add()_ não exibe/grava imediatamente a mensagem, mas apenas a diciona a _buffer_. Todas as chamas a _.add()_ irão concatenar a mensagem recebida até a próxima chamada em algum dos níveis _.debug(), .info(), .aviso(), .erro(), .critico()_. Na primeira chama de um destes níveis após uma (ou mais) chamada(s) ao método _.add()_ o *buffer* será concatenado à mensagem recebida por um destes métodos e o resultado será manipulado pelo log conforme os parametros definidos no intanciamento da classe e o método chamado. Essa função é útil para tratar mensagens com retorno condicional. Exemplo:
 
 ```
 log.add('Mensagem 1# ') ## não será exibida/registrada
@@ -344,15 +345,26 @@ log.add('Mensagem 2# ') ## não será exibida/registrada
 log.info('Mensagem 3) ## será exibida/registrada como nível "info" e com texto: "Mensagem 1# Mensagem 2# Mensagem 3"
 ```
 
-Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: ``message``, `corte=None`, `exit=None`.
+3) Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: `message`, `corte=None`, `exit=None`.
 
  - `message`: posicional e obrigatório. corresponde à mensagem a ser exibida
  - `corte`: o tamanho máximo da mensagem a ser exibida. opcional e se omitido, exibe a mensagem inteira. se fornecido, corta a mensagem no comprimento informado
  - `exit`: opcional. se informado (requer um código de retorno), aborta o script com o código informado. se omisso (padrão) a mensagem apenas é minutada pelo log, sem interferir no funcionamento do script
 
-Essa classe requer a importação do módulo `logging` no script em que for instanciada.
+4) O método `.filtra()` possui 3 parametros posicionais, todos opcionais: `log_file`, `dh_ini`, `dh_fim`.
 
-Exemplos de uso:
+Se os 3 forem omitidos, serão exibidas as entradas de log do arquivo corrente, definido no instanciamento da classe `lbx_logger`, registradas na última hora. Deste modo, o valor padrão para `dh_fim` é `now()`  e para `dh_ini` é `now()` menos 1 hora.
+
+Caso queira filtrar os registro de outro arquivo de log, que não seja o do script corrente, informe o endereço do arquivo no primeiro parametro.
+
+E caso queira alterar alterar o período de filtragem, informe nos parametros 2 e 3 a data/hora de início e fim do período. Estes dois parametros aceitam tanto um objeto do tipo `datetime` como uma string (que será convertida para datetime), desde que ela esteja no formato `dd/mm/aaaa hh:mm:[ss]` (segundos são opcionais).
+
+Considerando que os parametros são posicionais, caso queira omitir apenas um dos parametros, preencha a posição do parametro a ser omitido com `None`.
+
+A saída dessa função retorna um objeto, que pode ser salvo em disco ou impresso na tela.
+
+
+5) Exemplos de uso:
 
 ```
 from lbx_toolkit import lbx_logger 
@@ -394,6 +406,34 @@ except Exception as e:
 log.erro('Essa é uma mensagem de erro e abortará a execução do script', exit=1)
 
 log.info('Essa mensagem não será exibida pois o script foi abortado na mensagem anterior')
+
+# obtem os registros de log da última hora (comportamento padrão)
+filtra_log = log.search() 
+
+# obtem os registros das últimas 6 horas
+ultimas_6h = datetime.datetime.now() - datetime.timedelta(hours=6) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
+filtra_log = log.search(None, ultimas_6h) # None no 1º parametro impõe o log do arquivo corrente como padrão (definido em 'LogFile' e apontado no instanciamento da classe)
+
+# obtem os registros do dia 14/01/2020 até 3h atrás
+ultimas_3h = datetime.datetime.now() - datetime.timedelta(hours=3) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
+filtra_log = log.search(None, '14/01/2020 00:00', ultimas_3h) # 
+
+# obtem os registros do horário comercial do dia 23/12/2023 do arquivo salvo em C:\temp\outro_arquivo.log
+Outro_Log = Path(r'c:\temp\outro_arquivo.log')
+filtra_log = log.search(Outro_Log, '23/12/2023 08:00', '23/12/2023 18:00') # 
+
+# salva conteúdo filtrado em um arquivo:
+filtrado = 'filtered_log.txt'
+with open(filtado, 'w', encoding='ISO-8859-1') as output_file:  # indique o enconding conforme salvo (UTF-8 ou ISO-8859-1)
+    output_file.writelines(filta_log)    
+
+# mostra o conteúdo filtrado na tela
+print(''.join(filtra_log))
+
+# mostra o conteúdo filtrado na tela, listando apenas as os registros do nível "DEBUG"
+for line in filtered_lines:
+    if "DEBUG" in line:
+        print(line, end='')
 ```
 
 #### Classe **misc**

{lbxtoolkit-2.0.4 → lbxtoolkit-2.0.5}/lbxtoolkit/__init__.py

@@ -25,6 +25,7 @@ import re
 from unicodedata import normalize 
 import pygetwindow as gw
 import ctypes    
+import datetime
 
 locale.setlocale(locale.LC_ALL, 'pt_BR.UTF-8')
 
@@ -579,10 +580,11 @@ class lbx_logger: # Classe para gerenciar a saída para log
         self.logger = logging.getLogger(self.modulo)
         self.logger.setLevel(log_level)
         self.msg = ''
+        self.log_file_path = log_file_path
         
         if log_file_path:
             # Criando um handler para escrever em um arquivo de log
-            file_handler = logging.FileHandler(log_file_path)
+            file_handler = logging.FileHandler(self.log_file_path)
             file_handler.setLevel(log_level)  # Sempre registrar tudo no arquivo
             
             # Criando um handler para exibir no console
@@ -693,6 +695,85 @@ class lbx_logger: # Classe para gerenciar a saída para log
             handler.close()
             self.logger.removeHandler(handler)
 
+    def filtra(self, log_file, dh_ini, dh_fim):
+        # Validar parametros de entrada
+        if dh_ini:
+            if not isinstance(dh_ini, datetime.datetime):
+                if not re.fullmatch(r'([0-3][0-9]/[0-1][0-2]/[1-2][0-9]{3} [0-2][0-9]\:[0-6][0-9])(\:[0-6][0-9]){0,1}', dh_ini):
+                    self.logger.error(f'Data/Hora início {dh_ini} em formato inválido. Informe um objeto do tipo "datetime" ou uma string no formato "dd/mm/aaaa hh:mm:[ss]"')
+                    return None                
+                elif len(dh_ini) == 16:  # Formato 'dd/mm/yyyy hh:mm'
+                    dh_ini += ":00"
+                try:
+                    self.inicio = datetime.datetime.strptime(dh_ini, '%d/%m/%Y %H:%M:%S')
+                except:
+                    self.logger.error(f'Data/Hora início {dh_ini} em formato inválido. Informe um objeto do tipo "datetime" ou uma string no formato "dd/mm/aaaa hh:mm:[ss]"')
+                    return None
+            else:
+                self.inicio = dh_ini
+        else:
+            self.inicio = datetime.datetime.now() - datetime.timedelta(hours=1) ## assume a última hora como intervalo, se omisso
+
+        if dh_fim:
+            if not isinstance(dh_fim, datetime.datetime):
+                if not re.fullmatch(r'([0-3][0-9]/[0-1][0-2]/[1-2][0-9]{3} [0-2][0-9]\:[0-6][0-9])(\:[0-6][0-9]){0,1}', dh_ini):
+                    self.logger.error(f'Data/Hora fim {dh_fim} em formato inválido. Informe um objeto do tipo "datetime" ou uma string no formato "dd/mm/aaaa hh:mm:[ss]"')
+                    return None                
+                elif len(dh_fim) == 16:  # Formato 'dd/mm/yyyy hh:mm'
+                    dh_fim += ":00"
+                try:
+                    self.fim = datetime.datetime.strptime(dh_fim, '%d/%m/%Y %H:%M:%S')
+                except:
+                    self.logger.error(f'Data/Hora fim {dh_fim} em formato inválido. Informe um objeto do tipo "datetime" ou uma string no formato "dd/mm/aaaa hh:mm:[ss]"')
+                    return None
+            else:
+                self.fim = dh_fim
+        else:
+            self.fim = datetime.datetime.now() ## assume a última hora como intervalo, se omisso
+
+        if not log_file and not self.log_file_path:
+            self.logger.critical('Nenhum arquivo de log disponível. Log desta instância configurado apenas para exibição em tela, sem registro em arquivo')
+            return None
+        elif not log_file and self.log_file_path:
+            log_file_path = self.log_file_path
+        elif log_file:
+            if Path(log_file).is_file():
+                log_file_path = log_file
+            else:
+                self.logger.critical(f'Arquivo de log {log_file} não existe!')
+                return None
+        else:
+            self.logger.critical('Erro validação arquivo de entrada. Abortando!')
+            return None
+                   
+        # Função para verificar se a linha está dentro do intervalo de tempo
+        def is_within_time_range(timestamp, dh_inicio, dh_fim):
+            return dh_inicio <= timestamp <= dh_fim
+
+        # Ler e filtrar o arquivo de log com a codificação ISO-8859-1
+        with open(log_file_path, 'r', encoding='ISO-8859-1') as log_file:
+            log_lines = log_file.readlines()
+
+        # Variável para armazenar o último timestamp válido
+        last_valid_timestamp = None
+        filtered_lines = []
+
+        for line in log_lines:
+            try:
+                # Extraia a data e a hora da linha
+                timestamp_str = line.split()[0] + " " + line.split()[1]
+                timestamp = datetime.datetime.strptime(timestamp_str, '%Y-%m-%d %H:%M:%S,%f')
+                last_valid_timestamp = timestamp
+                if is_within_time_range(timestamp, self.inicio, self.fim):
+                    filtered_lines.append(line)
+            except Exception as e:
+                # Caso a linha não tenha um carimbo de tempo, use o último timestamp válido
+                if last_valid_timestamp and is_within_time_range(last_valid_timestamp, self.inicio, self.fim):
+                    filtered_lines.append(line)
+
+        # Retornar o objeto contendo as linhas filtradas
+        return filtered_lines
+                
 class misc: # Classe de miscelâneas
     def __init__(self):
         return None

{lbxtoolkit-2.0.4 → lbxtoolkit-2.0.5}/lbxtoolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lbxtoolkit
-Version: 2.0.4
+Version: 2.0.5
 Summary: Biblioteca de ferramentas LBX S/A
 Author: Cristiano P. Ferrari
 Author-email: boxferrari@gmail.com
@@ -52,6 +52,7 @@ Esta biblioteca possui ferramentas de uso recorrente para interação com banco
   - _.print_:            Contorna o manipulador de log e imprime diretamente na tela (stdout), sem formatar a mensagem nem registrar no arquivo
   - _.debug, .info, .aviso, .erro, .critico_:  Classifica as mensagens por nível de severidade/relevância e rediciona a saída (arquivo, tela, tela+arquivo) conforme a configuração do nível
   - _.stop_logging_:   Interrompe a manipulação das saídas pelo logger e restaura as saídas padrão (stdout/stderr) para a tela 
+  - _.filtra_:          Filtra os eventos do arquivo de log registrados em um intervalo de tempo específico
 
 **misc**:                 Classe de miscelâneas/diversos
   - _.seleciona_arquivo_: Abre um picker do sistema operacionar para selecionar um *arquivo* e retorna seu path
@@ -321,7 +322,7 @@ Para uso em APIs com autenticação JWT (JSON Web Token), OAuth, Bearer Token Au
 
 #### Classe **lbx_logger**
 
-Essa classe tem o propósito de manipular e formatar as mensagens de saída do script, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
+Essa classe requer a importação do módulo `logging` no script em que for instanciada e tem o propósito de manipular/formatar as mensagens de saída do script, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
 
 O comportamento padrão é registrar todas as saídas *simultaneamente* em tela e no arquivo com endereço informado no parâmetro `log_file_path`. Se este parametro for omisso no instanciamento da classe, as mensagens serão exibidas apenas na tela.
 
@@ -349,7 +350,7 @@ Os parametros para o instanciamento da classe são:
 - `ignore_console` Lista com os níveis de severidade a serem ignorados para *apresentação na tela*, registrando *apenas no arquivo* (quando informado no parametro `log_file_path`) e obedecendo ao nível mínimo estabelecido no parametro `log_level`. Note que omitir o parametro `log_file_path` e incluir um nível na lsita `ignore_console` implica em ignorar/suprimir esse nível de mensagem de qualquer apresentação.
 - `ignore_file` Mesma lógica do parametro `ignore_console`, mas com lógica invertida: suprime o registro do nível do arquivo e demonstra *apenas na tela*.
 
-As mensagem são manipuladas substituindo-se o comando `print()` pela chamada a um dos 5 métodos acima (_.add(), .debug(), .info(), .aviso(), .erro(), .critico()_). Exceto o método `.add()`, qualquer um dos demais métodos pode interromper a execução do script, através da passagem do parâmetro `exit`. Ao informar esse parametro na chamadada do método, atribua a ele o código de saída desejado (0 para normal, qualquer outro número para saída com erro). Exemplo:
+1) As mensagem são manipuladas substituindo-se o comando `print()` pela chamada a um dos 5 métodos acima (_.add(), .debug(), .info(), .aviso(), .erro(), .critico()_). Exceto o método `.add()`, qualquer um dos demais métodos pode interromper a execução do script, através da passagem do parâmetro `exit`. Ao informar esse parametro na chamadada do método, atribua a ele o código de saída desejado (0 para normal, qualquer outro número para saída com erro). Exemplo:
 
 ```
 log.erro('Essa mensagem apenas resulta em uma mensagem de nível ERROR')
@@ -359,7 +360,7 @@ log.erro('Essa mensagem resulta em uma mensagem de nível ERRO e encerra o scrip
 Qualquer chamada ao comando `print()`, uma vez instanciado manipulador de log, será registada como uma chamada ao método _.info()_ e registrada com este nível de severidade. 
 Para retornar ao comportamente padrão do comando print, ou interromper o manipulador, faça chamada ao método `.stop_logging()`
 
-O método _.add()_ não exibe/grava imediatamente a mensagem, mas apenas a diciona a _buffer_. Todas as chamas a _.add()_ irão concatenar a mensagem recebida até a próxima chamada em algum dos níveis _.debug(), .info(), .aviso(), .erro(), .critico()_. Na primeira chama de um destes níveis após uma (ou mais) chamada(s) ao método _.add()_ o *buffer* será concatenado à mensagem recebida por um destes métodos e o resultado será manipulado pelo log conforme os parametros definidos no intanciamento da classe e o método chamado. Essa função é útil para tratar mensagens com retorno condicional. Exemplo:
+2) O método _.add()_ não exibe/grava imediatamente a mensagem, mas apenas a diciona a _buffer_. Todas as chamas a _.add()_ irão concatenar a mensagem recebida até a próxima chamada em algum dos níveis _.debug(), .info(), .aviso(), .erro(), .critico()_. Na primeira chama de um destes níveis após uma (ou mais) chamada(s) ao método _.add()_ o *buffer* será concatenado à mensagem recebida por um destes métodos e o resultado será manipulado pelo log conforme os parametros definidos no intanciamento da classe e o método chamado. Essa função é útil para tratar mensagens com retorno condicional. Exemplo:
 
 ```
 log.add('Mensagem 1# ') ## não será exibida/registrada
@@ -367,15 +368,26 @@ log.add('Mensagem 2# ') ## não será exibida/registrada
 log.info('Mensagem 3) ## será exibida/registrada como nível "info" e com texto: "Mensagem 1# Mensagem 2# Mensagem 3"
 ```
 
-Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: ``message``, `corte=None`, `exit=None`.
+3) Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: `message`, `corte=None`, `exit=None`.
 
  - `message`: posicional e obrigatório. corresponde à mensagem a ser exibida
  - `corte`: o tamanho máximo da mensagem a ser exibida. opcional e se omitido, exibe a mensagem inteira. se fornecido, corta a mensagem no comprimento informado
  - `exit`: opcional. se informado (requer um código de retorno), aborta o script com o código informado. se omisso (padrão) a mensagem apenas é minutada pelo log, sem interferir no funcionamento do script
 
-Essa classe requer a importação do módulo `logging` no script em que for instanciada.
+4) O método `.filtra()` possui 3 parametros posicionais, todos opcionais: `log_file`, `dh_ini`, `dh_fim`.
 
-Exemplos de uso:
+Se os 3 forem omitidos, serão exibidas as entradas de log do arquivo corrente, definido no instanciamento da classe `lbx_logger`, registradas na última hora. Deste modo, o valor padrão para `dh_fim` é `now()`  e para `dh_ini` é `now()` menos 1 hora.
+
+Caso queira filtrar os registro de outro arquivo de log, que não seja o do script corrente, informe o endereço do arquivo no primeiro parametro.
+
+E caso queira alterar alterar o período de filtragem, informe nos parametros 2 e 3 a data/hora de início e fim do período. Estes dois parametros aceitam tanto um objeto do tipo `datetime` como uma string (que será convertida para datetime), desde que ela esteja no formato `dd/mm/aaaa hh:mm:[ss]` (segundos são opcionais).
+
+Considerando que os parametros são posicionais, caso queira omitir apenas um dos parametros, preencha a posição do parametro a ser omitido com `None`.
+
+A saída dessa função retorna um objeto, que pode ser salvo em disco ou impresso na tela.
+
+
+5) Exemplos de uso:
 
 ```
 from lbx_toolkit import lbx_logger 
@@ -417,6 +429,34 @@ except Exception as e:
 log.erro('Essa é uma mensagem de erro e abortará a execução do script', exit=1)
 
 log.info('Essa mensagem não será exibida pois o script foi abortado na mensagem anterior')
+
+# obtem os registros de log da última hora (comportamento padrão)
+filtra_log = log.search() 
+
+# obtem os registros das últimas 6 horas
+ultimas_6h = datetime.datetime.now() - datetime.timedelta(hours=6) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
+filtra_log = log.search(None, ultimas_6h) # None no 1º parametro impõe o log do arquivo corrente como padrão (definido em 'LogFile' e apontado no instanciamento da classe)
+
+# obtem os registros do dia 14/01/2020 até 3h atrás
+ultimas_3h = datetime.datetime.now() - datetime.timedelta(hours=3) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
+filtra_log = log.search(None, '14/01/2020 00:00', ultimas_3h) # 
+
+# obtem os registros do horário comercial do dia 23/12/2023 do arquivo salvo em C:\temp\outro_arquivo.log
+Outro_Log = Path(r'c:\temp\outro_arquivo.log')
+filtra_log = log.search(Outro_Log, '23/12/2023 08:00', '23/12/2023 18:00') # 
+
+# salva conteúdo filtrado em um arquivo:
+filtrado = 'filtered_log.txt'
+with open(filtado, 'w', encoding='ISO-8859-1') as output_file:  # indique o enconding conforme salvo (UTF-8 ou ISO-8859-1)
+    output_file.writelines(filta_log)    
+
+# mostra o conteúdo filtrado na tela
+print(''.join(filtra_log))
+
+# mostra o conteúdo filtrado na tela, listando apenas as os registros do nível "DEBUG"
+for line in filtered_lines:
+    if "DEBUG" in line:
+        print(line, end='')
 ```
 
 #### Classe **misc**

{lbxtoolkit-2.0.4 → lbxtoolkit-2.0.5}/setup.py

@@ -8,7 +8,7 @@ with open("README.md", "r", encoding='utf-8') as fh:
 
 setup(
     name='lbxtoolkit',
-    version='2.0.4',
+    version='2.0.5',
     packages=find_packages(),
     install_requires=[
         'psycopg2',