lbxtoolkit 2.2.1__py3-none-any.whl → 2.2.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lbxtoolkit/__init__.py +37 -35
- lbxtoolkit/api_rest.py +56 -56
- lbxtoolkit/auth_entra_id.py +22 -22
- lbxtoolkit/config_manager.py +6 -6
- lbxtoolkit/lbx_logger.py +114 -114
- lbxtoolkit/misc.py +8 -8
- lbxtoolkit/postgresql.py +89 -89
- lbxtoolkit/service.py +126 -126
- lbxtoolkit/service_windows.py +7 -7
- {lbxtoolkit-2.2.1.dist-info → lbxtoolkit-2.2.2.dist-info}/METADATA +192 -192
- lbxtoolkit-2.2.2.dist-info/RECORD +12 -0
- lbxtoolkit-2.2.1.dist-info/RECORD +0 -12
- {lbxtoolkit-2.2.1.dist-info → lbxtoolkit-2.2.2.dist-info}/WHEEL +0 -0
lbxtoolkit/__init__.py
CHANGED
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
|
|
4
4
|
Biblioteca com ferramentas utilitárias e de uso recorrente em aplicações de RPA para automações de processos.
|
|
5
5
|
|
|
6
|
-
Todas as classes e métodos deste módulo possuem **docstrings**.
|
|
6
|
+
Todas as classes e métodos deste módulo possuem **docstrings**.
|
|
7
|
+
Portanto, para ter acesso às informações de uso, use `nome_classe.__doc__`.
|
|
8
|
+
Exemplo:
|
|
7
9
|
|
|
8
10
|
```python
|
|
9
11
|
from lbxtoolkit import Servicer
|
|
@@ -15,66 +17,66 @@ print(help)
|
|
|
15
17
|
|
|
16
18
|
**auth_EntraID**
|
|
17
19
|
Usa o Microsoft Entra ID (antiga Azure AD) para evitar execução não autorizada de scripts
|
|
18
|
-
|
|
19
|
-
|
|
20
|
+
- `disclaimer` : Mensagem sobre a necessidade de autenticação
|
|
21
|
+
- `valida_grupo` : Autentica o usuário e aborta se checa não pertencer ao grupo de segurança
|
|
20
22
|
|
|
21
23
|
|
|
22
24
|
**postgreSQL**
|
|
23
25
|
Interage com o banco de dados PostgreSQL
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
26
|
+
- `db` Inicia sessão com o banco
|
|
27
|
+
- `csv_df` Lê arquivo CSV e gera Dataframe (pandas) a partir dele
|
|
28
|
+
- `db_insert_df` Insere informações de Dataframe em tabela do banco com estrutura equivalente
|
|
29
|
+
- `db_select` Retorna um cursor a partir de uma query
|
|
30
|
+
- `db_update` Executa update em tabelas
|
|
29
31
|
|
|
30
32
|
|
|
31
33
|
**api_rest**
|
|
32
34
|
Interage com APIs RESTfull, especialmente providas para a plataforma Sienge
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
35
|
+
- `auth_base` Autentica (HTTPBasicAuth) sessão na API
|
|
36
|
+
- `auth_bearer` Autentica sessão na API pelos métodos: OAuth, JWT, Bearer
|
|
37
|
+
- `endpoint_json` Realizad chama ao endpoint. Payload em formato `json` opcional.
|
|
38
|
+
- `trata_erro_sienge` Retorna a mensagem de erro do Sienge caso código de retorno seja diferente de 200.
|
|
39
|
+
- `close` Encerra a sessão autenticada
|
|
38
40
|
|
|
39
41
|
**lbx_logger**
|
|
40
42
|
Manipula e formata as mensagens de saída do script para direcioná-las para tela (stdout) e/ou arquivo de log
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
43
|
+
- `add` Adiciona a mensagem a um _buffer_ sem exibir, acumulando até a próxima chamada em algum dos níveis abaixo.
|
|
44
|
+
- `print` Contorna o manipulador de log e imprime diretamente na tela (stdout), sem formatar a mensagem nem registrar no arquivo
|
|
45
|
+
- `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
|
|
46
|
+
- `stop_logging` Interrompe a manipulação das saídas pelo logger e restaura as saídas padrão (stdout/stderr) para a tela
|
|
47
|
+
- `filtra` Filtra os eventos do arquivo de log registrados em um intervalo de tempo específico
|
|
46
48
|
|
|
47
49
|
**SafeLogger**
|
|
48
50
|
Intercepta as ordens de saída comandadas pelos métodos de lbx_logger e interrompe um daemon em execução antes de saír
|
|
49
51
|
|
|
50
52
|
**ConfigManager**
|
|
51
53
|
Permite a inicialização/instanciamento e o consumo de objetos entre classes e métodos independentes, inclusive métodos estáticos (sem instanciamento da classe), garantindo que todas as partes do código usem a mesma instância e, portanto, compartilhem a mesma configuração.
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
54
|
+
- `initialize` Inicialização com Argumentos Dinâmicos: O método initialize usa **kwargs para aceitar qualquer número de pares chave-valor, armazenando-os no dicionário da instância.
|
|
55
|
+
- `get` O método get aceita uma chave como argumento e retorna o valor correspondente do dicionário _config.
|
|
56
|
+
- `set` O método set permite adicionar ou atualizar dinamicamente valores no dicionário _config.
|
|
57
|
+
- `reset` O método reset limpa todas as configurações armazenadas, permitindo uma nova inicialização do ConfigManager com novos valores
|
|
56
58
|
|
|
57
59
|
**ServicoWindows**
|
|
58
60
|
Gerencia a instalação e execução de um daemon como um serviço do windows. Também assum o controle dos argumentos recebidos via linha de comando.
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
61
|
+
- `SvcInstall` Cria um serviço do windows com base neste script
|
|
62
|
+
- `SvcRemove` Remove o serviço do windows configurado à partir de `SvcInstall`
|
|
63
|
+
- `SvcStop` Para/Interrompe a execução do serviço do windows criado por este script (método herdado da classe pai _win32serviceutil.ServiceFramework_)
|
|
64
|
+
- `SvcDoRun` Inicializa a execução do serviço do windows criado por este script (método herdado da classe pai _win32serviceutil.ServiceFramework_)
|
|
63
65
|
|
|
64
66
|
**Servicer**
|
|
65
67
|
Classe base com a esrtutura padrão para a criação dameons/serviços do windows.
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
68
|
+
- `run`, `stop` Usados para iniciar (`run`) e parar (`stop`) a execução do daemon/serviço.
|
|
69
|
+
- `main` deve ser chamada para controlar a sua chamada inicial do script, tratando os argumentos da linha de comando
|
|
70
|
+
- `on_run` é o método que efetivamente executa o propósito do script quando o método pai `run` é executado
|
|
71
|
+
- `args_parser` é o método que define o comportamento do script quando o método `main` é executado (**`argpaser`**)
|
|
70
72
|
|
|
71
73
|
**misc**
|
|
72
74
|
Classe de miscelâneas/diversos
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
75
|
+
- `seleciona_arquivo` Abre um picker do sistema operacionar para selecionar um *arquivo* e retorna seu path
|
|
76
|
+
- `seleciona_dir` Abre um picker do sistema operacionar para selecionar um *diretório* e retorna seu path
|
|
77
|
+
- `normaliza` Limpa caracteres especiais e espaços de strings e retorna tudo em minúsculo
|
|
78
|
+
- `get_cmd_window` Captura a referencia da janela atual (cmd.exe) para retornar o foco à ela depois de chamar os pickers
|
|
79
|
+
- `maximize_console` Maxima a janela do console (cmd.exe)
|
|
78
80
|
|
|
79
81
|
## Instalação e uso:
|
|
80
82
|
|
lbxtoolkit/api_rest.py
CHANGED
|
@@ -7,81 +7,81 @@ from requests.auth import HTTPBasicAuth
|
|
|
7
7
|
|
|
8
8
|
class api_rest: # Classe para interação com APIs Rest (especialmente Sienge)
|
|
9
9
|
"""
|
|
10
|
-
|
|
10
|
+
#### Classe **api_rest**
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Destina-se a interatir com APIs RESTfull, em especial as publicadas pela SoftPlan para a [Plataforma Sienge](https://api.sienge.com.br/docs/).
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
A classe deve ser instanciada conforme sintaxe abaixo:
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
16
|
+
```python
|
|
17
|
+
api_rest(url, credenciais, cadencia, timeout=6, logger=None, headers={"Content-Type": "application/json"}, verify=True)
|
|
18
|
+
```
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
20
|
+
São nessários 2 parâmetros posicionais obrigatórios, e 5 parametros nominais facultativos (valor padrão, se omisso, indicado na sintaxe acima):
|
|
21
|
+
- `url`: o endereço da URL de autenticação da API
|
|
22
|
+
- `crednciais`: Dicionário com credenciais de autenticação.
|
|
23
|
+
- `cadencia` Número máximo de chamadas *por segudo* à API
|
|
24
|
+
- `timeout` Tempo máximo (segundos) para aguardar retorno à chamada. Padrão 6s, se omisso.
|
|
25
|
+
- `logger` O objeto _log handler_ para lidar com as informações de saída. Se não informado, todas as saídas serão direcionadas para a stdout.
|
|
26
|
+
- `headers` Cabeçalhos _http_ para a requisição à API.
|
|
27
|
+
- `verify` Verifica a validade do certificado SSL do servidor de destino da requisição.
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
29
|
+
Quanto às credenciais de autenticação, assim como a classe de interação com o PostgreSQL, elas precisam ser fornecidas na forma de um *dicionário*.
|
|
30
|
+
Para o método `api_rest.aut_basic()`, o formato deve ser:
|
|
31
|
+
```python
|
|
32
|
+
credenciais = {
|
|
33
|
+
'user': 'USUARIO_API',
|
|
34
|
+
'password': 'TOKEN_USUARIO'
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
Caso a autenticação seja pelo método `api_rest.aut_bearer()`, o dicionário deve corresponder ao formato previsto pelo endpoint e seu conteúdo será enviado como um JSON ao endereço indicado no parametro `url`
|
|
38
38
|
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
40
|
+
A classe possui 3 métodos:
|
|
41
|
+
- `api_rest.auth_basic()`: instanciamento da sessão autenticando pelo método HTTPBasicAuth
|
|
42
|
+
- `api_rest.auth_bearer()`: instanciamento da sessão autenticando pelos métodos OAuth, JWT, Bearer
|
|
43
|
+
- `api_rest.endpoint_json([endereço], [método], payload=None)`: para a chamada ao endpoint
|
|
44
|
+
- `close()` para encerra a instância/sessão
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
O consumo é feito pelo método `api_rest.endpoint_json` que suporta apenas APIs cujo payload (opcional) seja aceito no formato JSON.
|
|
47
47
|
|
|
48
|
-
|
|
49
|
-
|
|
48
|
+
Esse método espera 2 parametros posicionais obrigatórios: o endereço do endpoint e o verbo (get, post, patch ou put), tendo parametro opcional o objeto de 'payload' (json).
|
|
49
|
+
Note que o endereço do endpoint deve ser informado completo. A URL informada no instanciamento da classe corresponde apenas ao endereço de autenticação.
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
O tempo, em segundos, transcorrido entre a chamada a atual e a chamada anterior ao endpoint pode ser consultado pelo argumento `.Intervalo` no objeto recebido do retorno à chamada ao método `.endpoint_json`.
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
Da mesma forma, o tempo de espera imposto para respeitar a cadência do webservcie também pode ser consultado pelo argumento `.Espera`.
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
Exemplo de uso:
|
|
56
56
|
|
|
57
|
-
|
|
58
|
-
|
|
57
|
+
```python
|
|
58
|
+
from lbx_toolkit import api_rest
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
60
|
+
UrlBase=r'https://api.sienge.com.br/lbx/public/api/v1'
|
|
61
|
+
Credenciais = {
|
|
62
|
+
'user': 'USUARIO_API',
|
|
63
|
+
'password': 'TOKEN_USUARIO'
|
|
64
|
+
}
|
|
65
|
+
ApiSienge = api_rest(UrlBase,Credenciais,2.5) # limite de 2 requisições/segundo para cadência de chamada ao endpoint
|
|
66
|
+
Auth = ApiSienge.auth_basic()
|
|
67
67
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
68
|
+
Nutitulo=input('Numero do título:')
|
|
69
|
+
Nuparcela=input('Numero da parcela:')
|
|
70
|
+
Vencimento=input('Vencimento [AAAA-MM-DD]:')
|
|
71
|
+
Payload = {
|
|
72
|
+
"dueDate": f"{Vencimento}"
|
|
73
|
+
}
|
|
74
|
+
EndPoint = f'{UrlBase}/bills/{Nutitulo}/installments/{Nuparcela}'
|
|
75
75
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
76
|
+
#chama o endpoint e recebe o retorno no objeto AlteraVcto
|
|
77
|
+
AlteraVcto = ApiSienge.endpoint_json(EndPoint, 'patch', Payload)
|
|
78
|
+
```
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
No exemplo acima não é esperado que o endpoint retorne nenhum dado (`patch`).
|
|
81
81
|
|
|
82
|
-
|
|
82
|
+
Quando se usa o verbo `get` e se espera o retorno de algum dado, use o método `.json` do pacote `request` para acessar o objeto recebido.
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
Para uso em APIs com autenticação JWT (JSON Web Token), OAuth, Bearer Token Authentication, a construção é a mesma indicada acima, bastando-se usar `.auth_bearer()` ao invés de _.auth_basic()_, e ajustar o dicionário `credenciais` informado no instanciamento da classe, que deve ser estruturado conforme o padrão fornecido peo mantendor da API e será enviado como payload ao endpoint (`json=credenciais`).
|
|
85
85
|
|
|
86
86
|
"""
|
|
87
87
|
def __init__(self, url, credenciais, cadencia=3, timeout=6, logger=None, headers={"Content-Type": "application/json"}, verify=True):
|
lbxtoolkit/auth_entra_id.py
CHANGED
|
@@ -14,42 +14,42 @@ from webdriver_manager.chrome import ChromeDriverManager
|
|
|
14
14
|
|
|
15
15
|
class auth_EntraID: # Classe de autenticação de usuários no Microsoft Entra ID (antiga Azure AD)
|
|
16
16
|
"""
|
|
17
|
-
|
|
17
|
+
#### Classe **auth_EntraID**
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Este recurso tem o propósito de controlar as permissões de execução do script usando as credencias do ambiente AD em nuvem da Microsoft (Azure AD Microsoft Entra ID), abortando se a autentição falhar ou o usuário não pertencer ao grupo.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Essa classe possui apenas dois métodos:
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
23
|
+
- `auth_EntraID.disclaimer()`: apenas exibe uma tela de informações/instruções ao usuário.
|
|
24
|
+
- `auth_EntraID.valida_grupo([client_id], [client_secret], [tenant_id], timeout=60, log_file='auth_EntraID.log')`: efetua a autenticação do usuário e verifica se ele pertence ao grupo informado, abortando a execução caso não pertença ao grupo ou a autenticação não seja validada no tempo estabelecido. Os argumentos `timeout` e `log_file` são opcionais e, se omitidos, os valores aqui atribuídos serão adotados como padrão.
|
|
25
25
|
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
É necessário obter parametros da plataforma de identidade da Microsoft (AD Azure, agora Microsoft Entra ID), no [*Centro de administração do Microsoft Entra*](https://entra.microsoft.com).
|
|
27
|
+
Sugerimos não armazenar estas ou outras informações sensíveis no script. Considere usar o pacote `dotenv` para isso.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Os argumentos obrigatórios (posicionais) são:
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
1. `tenant_id` corresponde ao campo *ID do Locatário*, que pode ser obtido na página [visão geral de identidade do domínio](https://entra.microsoft.com/#blade/Microsoft_AAD_IAM/TenantOverview.ReactView)
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
2. `client_id` corresponde ao *ID do aplicativo (cliente)*, obtido na secção [_Identidade Aplicativos Registros de Aplicativo_](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade/quickStartType~/null/sourceType/Microsoft_AAD_IAM). Considere não reaproveitar aplicativos e criar um específico para essa finalidade.
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
3. `secret_id` corresponde ao *Valor* do _ID secreto_ (não ao próprio ID Secreto) do aplicativo. Este token não é passivel de consulta após gerado e para obtê-lo, é necessário criar um novo segredo para o aplicativo na subsecção _"Certificados e Segredos"_, após clicar no nome do aplicativo exibo na indicada no item (2). O token (_Valor do segredo_) deve ser copiado e anotado no ato da criação, pois *não é possível consultá-lo posteriormente*.
|
|
36
36
|
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
|
|
38
|
+
```python
|
|
39
|
+
from lbx_toolkit import auth_EntraID
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
client_id = 'SEU_CLIENT_ID'
|
|
42
|
+
client_secret = 'SEU_CLIENT_SECRET'
|
|
43
|
+
tenant_id = 'SEU_TENANT_ID'
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
|
|
45
|
+
# inicializa instância
|
|
46
|
+
auth = auth_EntraID(client_id, client_secret, tenant_id, timeout=60, log_file='auth_EntraID.log')
|
|
47
47
|
|
|
48
|
-
|
|
49
|
-
|
|
48
|
+
# exibe a mensagem padrão de aviso
|
|
49
|
+
auth.disclaimer()
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
auth.valida_grupo('Nome do Grupo de Distribuição')
|
|
52
|
+
# se usuário não pertencer a grupo informado, a execução do script é abortada.
|
|
53
53
|
```
|
|
54
54
|
"""
|
|
55
55
|
def __init__(self, client_id, client_secret, tenant_id, grupo, timeout=60, log_file='auth_EntraID.log'):
|
lbxtoolkit/config_manager.py
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
class ConfigManager: # Inicializa e recupera variáveis em ambiente de intercâmbio entre classes
|
|
2
2
|
"""
|
|
3
|
-
|
|
3
|
+
#### Classe **auth_EntraID**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
É um singleton que garante que todas as partes do código usem a mesma instância e, portanto, compartilhem a mesma configuração.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
- `initialize(chave1=valor1, ..., chaveN=valorN)` : O método initialize usa **kwargs para aceitar qualquer número de pares chave-valor, armazenando-os no dicionário _config da instância.
|
|
8
|
+
- `get('chave')`: O método get aceita uma chave como argumento e retorna o valor correspondente do dicionário _config.
|
|
9
|
+
- `set('chave', valor)`: O método set permite adicionar ou atualizar dinamicamente valores no dicionário _config.
|
|
10
|
+
- `reset`: O método reset limpa todas as configurações armazenadas, permitindo uma nova inicialização do ConfigManager com novos valores
|
|
11
11
|
"""
|
|
12
12
|
_instance = None
|
|
13
13
|
def __new__(cls):
|
lbxtoolkit/lbx_logger.py
CHANGED
|
@@ -7,146 +7,146 @@ from pathlib import Path
|
|
|
7
7
|
|
|
8
8
|
class lbx_logger: # Classe para gerenciar a saída para log
|
|
9
9
|
r"""
|
|
10
|
-
|
|
10
|
+
#### Classe **lbx_logger**
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Essa classe requer a importação do módulo `logging` e tem o propósito de manipular/formatar as mensagens de saída, alterando o formato e redirecionando destino padrão (stdout e stderr) para uma combinação de tela e/ou arquivo.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
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.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
A mensagens devem ser classificadas por grau de severidade/relevância, da menor para a maior, na seguinte ordem: *debug, info, warning (aviso), error (erro), critical (critico)*
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
A classificação do nível de serveridade da mensagem se dá pelo método escolhido para exibir a mensagem, correspondente aos níveis de severidade equivalentes.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
A classe deve ser instanciada conforme sintaxe abaixo:
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
22
|
+
```python
|
|
23
|
+
log = lbx_logger(log_file_path=None, log_level=logging.DEBUG, formato_log='%(asctime)s - %(levelname)s - %(message)s', modulo=None, ignore_console=None, ignore_file=None)
|
|
24
|
+
```
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Todos os parametros são nominativos e facultativos. Em caso de omissão, os valores padrão são assumidos conforme o exemplo acima.
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
Os parametros para o instanciamento da classe são:
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
30
|
+
- `log_file_path`: Define o caminho e o nome do arquivo de log. Se omisso, as mensagens serão todas direcionadas apenas para a tela.
|
|
31
|
+
- `log_level`: Define o nível mínimo de severidade das mensagens a serem manipuladas pelo logger. Se omisso, será assumido o nível mais baixo (_debug_). As mensagens com nível abaixo do especificado são descartadas. Os níveis devem ser informados de acordo com a sintaxe acima (prefixados com _logging._ e com o nome do nível em inglês e maiúsculas). Exemplo:
|
|
32
|
+
- `logging.DEBUG`: para manipular chamadas do método *.debug()* e acima.
|
|
33
|
+
- `logging.INFO`: para manipular chamadas do método *.info()* e acima.
|
|
34
|
+
- `logging.WARNING`: para manipular chamadas do método *.aviso()* e acima.
|
|
35
|
+
- `logging.ERROR`: para manipular chamadas do método *.erro()* e acima.
|
|
36
|
+
- `logging.CRITICAL`: para manipular chamadas do método *.critico()* e acima.
|
|
37
|
+
- `formato_log`: Define o formato em que a mensagem será apresentada. Se omisso, o padrá é *DATA_HORA - NIVEL - MENSAGEM*. Para maiores opções veja: [Atributos de log](https://docs.python.org/3/library/logging.html#logrecord-attributes)
|
|
38
|
+
- `modulo`: Nome do módulo para o qual os logs serão monitorados. Permite instanciar várias vezes a classe para criar manipuladores diferentes para módulos diferente. Informe o nome do módulo para criar um log específico para ele ou simplesmente omita o parametro para criar um log para o script em geral.
|
|
39
|
+
- `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.
|
|
40
|
+
- `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*.
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
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:
|
|
43
43
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
44
|
+
```python
|
|
45
|
+
log.erro('Essa mensagem apenas resulta em uma mensagem de nível ERROR')
|
|
46
|
+
log.erro('Essa mensagem resulta em uma mensagem de nível ERRO e encerra o script com código de retorno -1', exit=-1)
|
|
47
|
+
```
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
|
|
49
|
+
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.
|
|
50
|
+
Para retornar ao comportamente padrão do comando print, ou interromper o manipulador, faça chamada ao método `.stop_logging()`
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
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:
|
|
53
53
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
54
|
+
```python
|
|
55
|
+
log.add('Mensagem 1# ') ## não será exibida/registrada
|
|
56
|
+
log.add('Mensagem 2# ') ## não será exibida/registrada
|
|
57
|
+
log.info('Mensagem 3) ## será exibida/registrada como nível "info" e com texto: "Mensagem 1# Mensagem 2# Mensagem 3"
|
|
58
|
+
```
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
3. Os métodos que exibem as mensagens (`.debug()`,`.info()`,`.aviso()`, `.erro()`, `.critico()`) possuem 3 parametros: `message`, `corte=None`, `exit=None`.
|
|
61
61
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
62
|
+
- `message`: posicional e obrigatório. corresponde à mensagem a ser exibida
|
|
63
|
+
- `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
|
|
64
|
+
- `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
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
4. O método `.filtra()` possui 3 parametros posicionais, todos opcionais: `log_file`, `dh_ini`, `dh_fim`.
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
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.
|
|
69
69
|
|
|
70
|
-
|
|
70
|
+
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.
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
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).
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
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`.
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
A saída dessa função retorna um objeto, que pode ser salvo em disco ou impresso na tela.
|
|
77
77
|
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
5. Exemplos de uso:
|
|
80
80
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
DirBase = Path('./') # diretório corrente do script
|
|
88
|
-
BaseName = os.path.splitext(os.path.basename(__file__))[0] # nome do script sem extensão
|
|
89
|
-
LogFile = Path(DirBase, BaseName + '.log') # salva logs no diretório corrente, em um arquivo nomeado com nome do script + extensão ".log"
|
|
90
|
-
|
|
91
|
-
### instancia o manipulador para tratar todas as mensagens (nível DEBUG acima),
|
|
92
|
-
# mas suprime a apresentação em tela das mensagens de nível "DEBUG" na tela,
|
|
93
|
-
# apenas registrando-as somente no arquivo
|
|
94
|
-
# e sumprime o registro no arquivo das mensagens de nível "ERROR",
|
|
95
|
-
# mostrando-as apenas na tela
|
|
96
|
-
log = lbx_logger(LogFile, logging.DEBUG, ignore_console=[logging.DEBUG], ignore_file=[logging.ERROR])
|
|
97
|
-
|
|
98
|
-
# Exemplo de mensagens de log
|
|
99
|
-
log.debug('Esta é uma mensagem de debug')
|
|
100
|
-
log.info('Esta é uma mensagem informativa')
|
|
101
|
-
log.add('Esta mensagem não será exibida agora, mas acumulada no buffer# ')
|
|
102
|
-
log.aviso('Esta é uma mensagem de aviso')
|
|
103
|
-
log.erro('Esta é uma mensagem de erro')
|
|
104
|
-
log.erro('Esta é uma mensagem erro muito comprida e será limitada a 40 caracteres, o restante será cortado e ingorado ao ser manipulado', 40)
|
|
105
|
-
log.critico('Esta é uma mensagem crítica')
|
|
106
|
-
|
|
107
|
-
# Exemplo de função que gera uma exceção
|
|
108
|
-
def funcao_com_erro():
|
|
109
|
-
raise ValueError('Este é um erro de exemplo')
|
|
110
|
-
|
|
111
|
-
# Testando redirecionamento de print e captura de exceção
|
|
112
|
-
print('Mensagem de teste via print')
|
|
113
|
-
try:
|
|
114
|
-
funcao_com_erro()
|
|
115
|
-
except Exception as e:
|
|
116
|
-
print(f'Capturado um erro: {e}')
|
|
117
|
-
|
|
118
|
-
log.erro('Essa é uma mensagem de erro e abortará a execução do script', exit=1)
|
|
119
|
-
|
|
120
|
-
log.info('Essa mensagem não será exibida pois o script foi abortado na mensagem anterior')
|
|
121
|
-
|
|
122
|
-
# obtem os registros de log da última hora (comportamento padrão)
|
|
123
|
-
filtra_log = log.search()
|
|
124
|
-
|
|
125
|
-
# obtem os registros das últimas 6 horas
|
|
126
|
-
ultimas_6h = datetime.datetime.now() - datetime.timedelta(hours=6) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
|
|
127
|
-
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)
|
|
128
|
-
|
|
129
|
-
# obtem os registros do dia 14/01/2020 até 3h atrás
|
|
130
|
-
ultimas_3h = datetime.datetime.now() - datetime.timedelta(hours=3) ## carimbo de tempo de 6 horas atrás !!! requer>> import datetime
|
|
131
|
-
filtra_log = log.search(None, '14/01/2020 00:00', ultimas_3h) #
|
|
132
|
-
|
|
133
|
-
# obtem os registros do horário comercial do dia 23/12/2023 do arquivo salvo em C:\temp\outro_arquivo.log
|
|
134
|
-
Outro_Log = Path(r'c:\temp\outro_arquivo.log')
|
|
135
|
-
filtra_log = log.search(Outro_Log, '23/12/2023 08:00', '23/12/2023 18:00') #
|
|
136
|
-
|
|
137
|
-
# salva conteúdo filtrado em um arquivo:
|
|
138
|
-
filtrado = 'filtered_log.txt'
|
|
139
|
-
with open(filtado, 'w', encoding='ISO-8859-1') as output_file: # indique o enconding conforme salvo (UTF-8 ou ISO-8859-1)
|
|
140
|
-
output_file.writelines(filta_log)
|
|
141
|
-
|
|
142
|
-
# mostra o conteúdo filtrado na tela
|
|
143
|
-
print(''.join(filtra_log))
|
|
81
|
+
```python
|
|
82
|
+
from lbx_toolkit import lbx_logger
|
|
83
|
+
import logging
|
|
84
|
+
import os
|
|
85
|
+
from pathlib import Path
|
|
144
86
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
87
|
+
DirBase = Path('./') # diretório corrente do script
|
|
88
|
+
BaseName = os.path.splitext(os.path.basename(__file__))[0] # nome do script sem extensão
|
|
89
|
+
LogFile = Path(DirBase, BaseName + '.log') # salva logs no diretório corrente, em um arquivo nomeado com nome do script + extensão ".log"
|
|
90
|
+
|
|
91
|
+
### instancia o manipulador para tratar todas as mensagens (nível DEBUG acima),
|
|
92
|
+
# mas suprime a apresentação em tela das mensagens de nível "DEBUG" na tela,
|
|
93
|
+
# apenas registrando-as somente no arquivo
|
|
94
|
+
# e sumprime o registro no arquivo das mensagens de nível "ERROR",
|
|
95
|
+
# mostrando-as apenas na tela
|
|
96
|
+
log = lbx_logger(LogFile, logging.DEBUG, ignore_console=[logging.DEBUG], ignore_file=[logging.ERROR])
|
|
97
|
+
|
|
98
|
+
# Exemplo de mensagens de log
|
|
99
|
+
log.debug('Esta é uma mensagem de debug')
|
|
100
|
+
log.info('Esta é uma mensagem informativa')
|
|
101
|
+
log.add('Esta mensagem não será exibida agora, mas acumulada no buffer# ')
|
|
102
|
+
log.aviso('Esta é uma mensagem de aviso')
|
|
103
|
+
log.erro('Esta é uma mensagem de erro')
|
|
104
|
+
log.erro('Esta é uma mensagem erro muito comprida e será limitada a 40 caracteres, o restante será cortado e ingorado ao ser manipulado', 40)
|
|
105
|
+
log.critico('Esta é uma mensagem crítica')
|
|
106
|
+
|
|
107
|
+
# Exemplo de função que gera uma exceção
|
|
108
|
+
def funcao_com_erro():
|
|
109
|
+
raise ValueError('Este é um erro de exemplo')
|
|
110
|
+
|
|
111
|
+
# Testando redirecionamento de print e captura de exceção
|
|
112
|
+
print('Mensagem de teste via print')
|
|
113
|
+
try:
|
|
114
|
+
funcao_com_erro()
|
|
115
|
+
except Exception as e:
|
|
116
|
+
print(f'Capturado um erro: {e}')
|
|
117
|
+
|
|
118
|
+
log.erro('Essa é uma mensagem de erro e abortará a execução do script', exit=1)
|
|
119
|
+
|
|
120
|
+
log.info('Essa mensagem não será exibida pois o script foi abortado na mensagem anterior')
|
|
121
|
+
|
|
122
|
+
# obtem os registros de log da última hora (comportamento padrão)
|
|
123
|
+
filtra_log = log.search()
|
|
124
|
+
|
|
125
|
+
# obtem os registros das últimas 6 horas
|
|
126
|
+
ultimas_6h = datetime.datetime.now() - datetime.timedelta(hours=6) ## carimbo de tempo de 6 horas atrás !!! requer import datetime
|
|
127
|
+
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)
|
|
128
|
+
|
|
129
|
+
# obtem os registros do dia 14/01/2020 até 3h atrás
|
|
130
|
+
ultimas_3h = datetime.datetime.now() - datetime.timedelta(hours=3) ## carimbo de tempo de 6 horas atrás !!! requer import datetime
|
|
131
|
+
filtra_log = log.search(None, '14/01/2020 00:00', ultimas_3h) #
|
|
132
|
+
|
|
133
|
+
# obtem os registros do horário comercial do dia 23/12/2023 do arquivo salvo em C:\temp\outro_arquivo.log
|
|
134
|
+
Outro_Log = Path(r'c:\temp\outro_arquivo.log')
|
|
135
|
+
filtra_log = log.search(Outro_Log, '23/12/2023 08:00', '23/12/2023 18:00') #
|
|
136
|
+
|
|
137
|
+
# salva conteúdo filtrado em um arquivo:
|
|
138
|
+
filtrado = 'filtered_log.txt'
|
|
139
|
+
with open(filtado, 'w', encoding='ISO-8859-1') as output_file: # indique o enconding conforme salvo (UTF-8 ou ISO-8859-1)
|
|
140
|
+
output_file.writelines(filta_log)
|
|
141
|
+
|
|
142
|
+
# mostra o conteúdo filtrado na tela
|
|
143
|
+
print(''.join(filtra_log))
|
|
144
|
+
|
|
145
|
+
# mostra o conteúdo filtrado na tela, listando apenas as os registros do nível "DEBUG"
|
|
146
|
+
for line in filtered_lines:
|
|
147
|
+
if "DEBUG" in line:
|
|
148
|
+
print(line, end='')
|
|
149
|
+
```
|
|
150
150
|
"""
|
|
151
151
|
class LevelFilter(logging.Filter):
|
|
152
152
|
def __init__(self, levels_to_ignore):
|