1r"""
  2# O que é
  3
  4Este software permite processar os dados de muitos arquivos de notas fiscais eletrônicas
  5e transformá-los em um conjunto de dados prontos para ser analisado por um analista de
  6dados ou incorporado em uma aplicação para empresas.
  7
  8> [!WARNING]
  9> Este projeto ainda está em fase experimental e deve ser usado com cautela, embora haja
 10> um esforço para tal, ainda não é possível validar os dados coletados com total clareza.
 11
 12Abaixo você pode encontrar instruções para [instalar](#instalando) e algumas
 13[instruções rápidas](#instrucoes-rapidas) de uso, para ver a documentação de todos os
 14recursos implementados no NF-Logic, acesse as páginas dedicadas para cada submódulo
 15([`api`](/nflogic/api.html) e [`cli`](/nflogic/cli.html)) indicados na barra lateral.
 16
 17# Instalando
 18
 19A maneira recomendada de instalar o `nflogic` como uma API é através do
 20[`PyPI`](https://pypi.org/project/nflogic/) usando o console do seu computador:
 21
 22```bash
 23pip install nflogic
 24```
 25
 26Caso queira usar como uma linha de comando, a maneira recomendada é primeiramente
 27instalar o `pipx` seguindo
 28[estas instruções](https://packaging.python.org/pt-br/latest/guides/installing-stand-alone-command-line-tools/),
 29e depois usá-lo para instalar o `nflogic`:
 30
 31```bash
 32pipx install nflogic
 33```
 34
 35# Instruções rápidas
 36
 37Aqui estão alguns exemplos simples para aproveitar as principais funcionalidades do
 38`nflogic` rapidamente.
 39
 40## Processando arquivos dentro de uma pasta
 41
 42A principal funcionalidade do `nflogic` está em processar documentos XML de notas fiscais
 43eletrônicas, para isso:
 44
 45- **API**
 46
 47  ```python
 48  import nflogic.api
 49  nflogic.parse_dir(dir_path="/full/path/to/directory", buy=False)
 50  ```
 51
 52- **CLI**
 53
 54  ```bash
 55  nflogic parse --ParseTo=seller "/full/path/to/directory"
 56  ```
 57
 58Estes comandos são equivalentes, e vão registrar os dados obtidos no diretório informado
 59como vendas realizadas pelo vendedor que estiver informado no próprio documento. Caso
 60existam múltiplos vendedores, uma tabela será construída para cada um que for encontrado.
 61
 62Os dados são armazenados em um banco de dados que fica junto ao local de instalação do
 63`nflogic`. A maneira recomendada para obter o local onde o banco de dados está é
 64pela API:
 65
 66```python
 67import nflogic.api
 68print(nflogic.DB_PATH)
 69```
 70
 71Caso não queira usar a API, você pode encontrar o banco de dados usando este comando,
 72caso tenha instalado com `pip`:
 73
 74```bash
 75pip show nflogic
 76```
 77
 78ou este, caso tenha instalado com `pipx`:
 79
 80```bash
 81pipx runpip nflogic show nflogic
 82```
 83
 84Procure pela linha que começa com "Location:" entre no diretóiro informado, e a partir
 85de lá, o banco de dados será encontrado em "`nflogic/database/db.sqlite`".
 86
 87## Verificando erros
 88
 89Depois de processar muitos dados em massa, é possível que o `nflogic` encontre falhas em
 90alguns arquivos, dependendo da quantidade de notas fiscais processadas, você pode ter
 91muitos arquivos para analisar. O `nflogic` permite ver um resumo das falhas de
 92processamento dos arquivos, indicando as mensagens de erro emitidas junto com a etapa do
 93processamento em que a falha ocorreu.
 94
 95O `nflogic` faz o melhor possível para identificar o nome do vendedor ou comprador da
 96nota, salva os erros em *caches* separados por nome. Quando não é possível, o erro é
 97registrado em um arquivo comum para todos os documentos em que o nome não pode ser
 98identificado, para listar os nomes dos arquivos de cache:
 99
100- **API**
101
102  ```python
103  import nflogic.api
104  # obtenha uma lista com o nome dos arquivos de cache
105  cachenames = nflogic.cache.get_cachenames()
106  # se algum erro ja tiver sido registrado, mostre na tela (stdout) o nome do cache
107  # e o resumo dos erros obtidos
108  for cn in cachenames:
109      error_df = nflogic.rebuild_errors(cachename=cn)
110      summary = nflogic.summary_err_types(err_df=error_df)
111      print(f"{cn}\n----", summary.to_string(), "\n", sep="\n")
112  ```
113
114    > [!NOTE]
115    > Explicando um pouco o código acima:
116    > 1. A função `rebuild_errors()` vai tentar repetir o procedimento que falhou
117    >    anteriormente, registrando todas as informações pertinentes de falhas em um
118    >    [`pandas.DataFrame`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html);
119    > 2. A função `summary_err_types` agrupa os erros similares por tipo, retornando um
120    >    `pandas.DataFrame` mais conciso.
121
122- **CLI**
123
124  Veja os nomes de cache disponíveis com:
125
126  ```bash
127  nflogic cachenames
128  ```
129
130  Depois veja o resumo dos erros, substituindo `[CACHENAME]` por um dos nomes listados
131  anteriormente:
132
133  ```bash
134  nflogic errors --summary [CACHENAME]
135  ```
136
137Usar a flag `--summary` faz com que retorne a tabela resumida dos erros agregados por
138tipo, omití-la retornaria o conjunto de dados completo.
139
140## Corrigindo erros ou atualizando o NF-Logic
141
142Os problemas de *parsing* podem ser corrigidos localmente usando um editor de texto para
143modificar o código fonte do `nflogic`. Por se tratar de um programa interpretado, e não
144compilado, alterações no código são refletidas diretamente no comportamento da CLI
145localmente.
146
147Você pode ajudar a melhorar a qualidade dos *parsers* oferecendo alguma
148[contribuição](#como-contribuir) para o desenvolvimento deste projeto, caso isso não
149seja possível, mantenha sua instalação do NF-Logic atualizada, o problema que você
150enfrenta pode ser corrigido em alguma atualização futura. Para atualizar a sua
151instalação:
152
153- **Pelo `pip`**
154
155  ```bash
156  pip install --upgrade nflogic
157  ```
158
159- **Pelo `pipx`**
160
161  ```bash
162  pipx upgrade nflogic
163  ```
164
165Leia as últimas linhas do resultado retornado para saber se alguma nova versão foi
166instalada, ou se você já está na versão mais recente.
167
168## Processando arquivos que já falharam
169
170Como já sabemos como [verificar erros](#verificando-erros), podemos pular para a parte em
171que vemos como podemos fazer com que o `nflogic` tente processar novamente os arquivos que
172já deram erro no passado:
173
174- **API**
175
176  ```python
177  import nflogic.api
178  nflogic.parse_cache(cachename="SOME_CACHE_NAME", full_parse=True)
179  ```
180
181Neste caso, `cachename` deve ser um dos nomes de cache retornados por
182`nflogic.cache.get_cachenames()`, e `full_parse` indica se devem ser extraídos apenas os
183metadados da nota fiscal, ou também as informações transacionais, como nomes dos produtos
184ou valores unitários.
185
186- **CLI**
187
188  ```bash
189  nflogic parse-cache [CACHENAME]
190  ```
191
192A versão de CLI atualmente sempre processa os dados dos documentos em cache usando
193`full_parse=True`.
194
195# Como contribuir
196
197Caso você tenha capacidade para entender o problema encontrado, e tenha uma sugestão para
198alterar o código fonte do *NF-Logic*, considere abrir uma
199[*issue*](https://github.com/VFLins/nflogic/issues) para informar sobre a existência do
200problema. Se você também se sente capaz de resolver o problema encontrado, sinta-se livre
201para propor uma [*pull request*](https://github.com/VFLins/nflogic/pulls) para que esta
202mudança afete os demais usuários na próxima versão do *NF-Logic*.
203"""
204
205from nflogic.api import (
206    db,
207    cache,
208    parse,
209    CACHE_DIR,
210    rebuild_errors,
211    summary_err_types,
212    xml_files_in_dir,
213    parse_dir,
214    parse_cache,
215)