edne-correios-loader


Nameedne-correios-loader JSON
Version 0.1.2 PyPI version JSON
download
home_page
SummaryLoad Brazilian Correios' e-DNE Basico text files into your database to enable CEP search
upload_time2023-10-11 17:19:03
maintainer
docs_urlNone
author
requires_python>=3.8
license
keywords brasil cep correios dne address edne endereço
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # e-DNE Correios Loader

[![PyPI - Version](https://img.shields.io/pypi/v/edne-correios-loader.svg)](https://pypi.org/project/edne-correios-loader)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/edne-correios-loader.svg)](https://pypi.org/project/edne-correios-loader)
[![codecov](https://codecov.io/gh/cauethenorio/edne-correios-loader/graph/badge.svg?token=HP9C86U1LX)](https://codecov.io/gh/cauethenorio/edne-correios-loader)

Programa de linha de comando para carregar arquivos do e-DNE Basico dos Correios para um banco de
dados (PostgreSQL, MySQL, SQLite e outros) e criar uma tabela única para consulta de CEPs.

---

### [English version 🇺🇸](README-en.md)

## Funcionalidades

- Carrega arquivos do DNE Básico dos Correios para um banco de dados
- Cria uma tabela unificada para consulta de CEPs
- Suporta os bancos de dados PostgreSQL, MySQL, SQLite entre outros
- Permite atualização dos dados sem interrupção do serviço
 

## Propósito

O DNE (Diretório Nacional de Endereços) é um banco de dados oficial e exclusivo dos Correios,
que contém mais de 900 mil CEP de todo o Brasil, constituído de elementos de endereçamento
(descrição de logradouros, bairros, municípios, vilas, povoados) e Códigos de Endereçamento
Postal - CEP.

Esse banco de dados é disponibilizado em duas versões, o __e-DNE Básico__ e o __e-DNE Máster__.
Ambas contêm todos os CEPs do Brasil, com elementos de endereçamento até nível de seção
de logradouro, porém diferem no formato. O e-DNE Básico é composto por vários arquivos de texto
(`.txt`) que precisam ser processados e transferidos para um banco de dados para poderem ser
consultados. Já o e-DNE Máster é um banco de dados no formato MS-Access (`.mdb`) pronto para uso.

O DNE é de propriedade dos Correios e pode ser adquirido através de seu e-commerce. Atualmente
(Outubro de 2023) a versão Máster custa R$ 3.187,65 e a versão Básica custa R$ 1.402,5.
Ambas as versões garantem um ano de atualizações após a data da compra.

[__Para clientes com contrato com os Correios, o e-DNE Básico pode ser adquirido gratuitamente.__](https://www.correios.com.br/enviar/marketing-direto/saiba-mais-nacional)

Esse projeto facilita o uso do e-DNE Básico, que é mais barato e mais fácil de ser adquirido,
processando os arquivos de texto e transferindo-os para um banco de dados, ele também cria uma
tabela única para consulta de CEPs (não inclusa no DNE, onde CEPs de diferentes tipos ficam em
tabelas diferentes) e permite que sua base seja atualizada com novas versões do e-DNE, lançadas
quinzenalmente pelos Correios.


## Instalação

O `edne-correios-loader` pode ser instalado através do `pip`:

```shell
pip install edne-correios-loader
```

Também será necessário instalar o driver do banco de dados que será utilizado. Aqui estão algumas
instruções de como instalar os drivers para os bancos de dados mais comuns:

### PostgreSQL

Para o PostgreSQL, o driver `psycopg2-binary` pode ser instalado utilizando um
[extra](https://peps.python.org/pep-0508/#extras):
```shell
pip install edne-correios-loader[postgresql]
```

Se não houver uma versão compilada do `psycopg2` para seu sistema operacional e versão do python,
você precisará instalar algumas bibliotecas para poder compilar o driver. Outra opção é instalar o
driver `pg8000` para o PostgreSQL, que é escrito totalmente em Python e não precisa ser compilado.

### MySQL

Para o MySQL, o driver `mysqlclient` pode ser instalado utilizando um
[extra](https://peps.python.org/pep-0508/#extras):
```shell
pip install edne-correios-loader[mysql]
```

### SQLite

O Python já disponibiliza a biblioteca `sqlite3` para comunicação com o SQLite, portanto não é
necessária nenhuma instrução adicional.

### Outros

A biblioteca `sqlalchemy` é utilizada para comunicação com o banco de dados, portanto qualquer banco
de dados suportado por ela pode ser utilizado, como o Microsoft SQL Server e Oracle. Para instalar
o driver de um banco de dados não listado aqui, consulte a documentação do SQLAlchemy:
https://docs.sqlalchemy.org/en/20/dialects/index.html


## Utilização

### Linha de comando

A importação dos dados pode ser executada através da linha de comando, com o
comando `edne-correios-loader load`.

```shell
$ edne-correios-loader load --help

Usage: edne-correios-loader load [OPTIONS]

  Load DNE data into a database.

Options:
  -s, --dne-source <path/zip-file/url>
                                  Path or URL with the DNE file/dir to be
                                  imported
  -db, --database-url <url>       Database URL where the DNE data will be
                                  imported to  [required]
  --tables [unified-cep-only|cep-tables|all]
                                  Which tables to keep in the database after
                                  the import
  -v, --verbose                   Enables verbose mode.
  -h, --help                      Show this message and exit.
```

#### Opções

As seguintes opções estão disponíveis:
- __`--dne-source`__ **(opcional)**

  Origem do e-DNE a ser importado. Pode ser:
    - Uma URL apontando para um arquivo ZIP com o e-DNE
    - O caminho local para um arquivo ZIP com o e-DNE
    - O caminho local para um diretório contendo os arquivos do e-DNE
    
  Se essa opcão não for informada, o último e-DNE Básico disponível no site dos
  Correios será baixado e usado como fonte. **Utilize essa opção apenas se você
  tiver um contrato com os Correios**.
 

- __`--database-url`__ **(obrigatório)**

  URL do banco de dados onde os dados do e-DNE serão importados. A URL deve seguir o
  padrão `dialect+driver://username:password@host:port/database`, onde:
    - `dialect` é o nome do banco de dados, como `postgresql`, `mysql`, `sqlite`, etc.
    - `driver` é o nome do driver do banco de dados, como `psycopg2`, `mysqlclient`,
      `pg8000`, etc. Se não especificado, o driver mais popular é utilizado automaticamente.
    - `username` é o nome de usuário do banco de dados
    - `password` é a senha do usuário do banco de dados
    - `host` é o endereço do servidor do banco de dados
    - `port` é a porta do servidor do banco de dados
    - `database` é o nome do banco de dados

  Mais informações sobre o formato da URL podem ser encontradas na documentação do
    [SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)
 

- __`--tables`__ **(opcional)**

  Define quais tabelas serão mantidas no banco de dados após a importação. Pode ser:
    - `unified-cep-only`: Mantém apenas a tabela unificada de CEPs
    - `cep-tables`: Mantém apenas as tabelas com CEPs, separadas por tipo
    - `all`: Mantém todas as tabelas do DNE

  Quando não especificado, a opção `unified-cep-only` é utilizada por padrão, mantendo
  apenas a tabela unificada de CEPs.


- __`--verbose`__ **(opcional)**

  Habilita o modo verboso, que exibe informações de DEBUG úteis para resolver problemas
  na execução do comando

#### Exemplos de uso

Importa o e-DNE Básico direto do site dos correios para um banco de dados SQLite local,
mantendo apenas a tabela unificada:
```shell
edne-correios-loader load --database-url sqlite:///dne.db
```

Importa o e-DNE Básico de um arquivo ZIP para um banco de dados PostgreSQL local, mantendo
todas as tabelas com CEPs:
```shell
edne-correios-loader load \
  --dne-source /path/to/dne.zip \
  --database-url postgresql://user:pass@localhost:5432/mydb \
  --tables cep-tables
```

Importa o e-DNE Básico de um diretório para um banco de dados MySQL local, mantendo todas
as tabelas:
```shell
edne-correios-loader load \
  --dne-source /path/to/dne/dir \
  --database-url mysql+mysqlclient://user:pass@localhost:3306/mydb \
  --tables all
```

O output do comando deve variar conforme as opções utilizadas, mas deve ser
parecido com o seguinte:
```
Starting DNE Correios Loader v0.1.1

Connecting to database...

Resolving DNE source...

No DNE source provided, the latest DNE will be downloaded from Correios website
Downloading DNE file  [####################################]  100%

Creating tables:
- cep_unificado
- log_localidade
- log_bairro
- log_cpc
- log_logradouro
- log_grande_usuario
- log_unid_oper

Cleaning tables

Populating table log_localidade
  Reading LOG_LOCALIDADE.TXT
  Inserted 11219 rows into table "log_localidade"

Populating table log_bairro
  Reading LOG_BAIRRO.TXT
  Inserted 64456 rows into table "log_bairro"

Populating table log_cpc
  Reading LOG_CPC.TXT
  Inserted 2133 rows into table "log_cpc"

Populating table log_logradouro
  Reading LOG_LOGRADOURO_RS.TXT
  Reading LOG_LOGRADOURO_RR.TXT
  Reading LOG_LOGRADOURO_SC.TXT
  Reading LOG_LOGRADOURO_SP.TXT
  Reading LOG_LOGRADOURO_SE.TXT
  Reading LOG_LOGRADOURO_PI.TXT
  Reading LOG_LOGRADOURO_MS.TXT
  Reading LOG_LOGRADOURO_AP.TXT
  Reading LOG_LOGRADOURO_MG.TXT
  Reading LOG_LOGRADOURO_MT.TXT
  Reading LOG_LOGRADOURO_AC.TXT
  Reading LOG_LOGRADOURO_MA.TXT
  Reading LOG_LOGRADOURO_TO.TXT
  Reading LOG_LOGRADOURO_AL.TXT
  Reading LOG_LOGRADOURO_CE.TXT
  Reading LOG_LOGRADOURO_BA.TXT
  Reading LOG_LOGRADOURO_AM.TXT
  Reading LOG_LOGRADOURO_ES.TXT
  Reading LOG_LOGRADOURO_PR.TXT
  Reading LOG_LOGRADOURO_PE.TXT
  Reading LOG_LOGRADOURO_GO.TXT
  Reading LOG_LOGRADOURO_RN.TXT
  Reading LOG_LOGRADOURO_RO.TXT
  Reading LOG_LOGRADOURO_DF.TXT
  Reading LOG_LOGRADOURO_RJ.TXT
  Reading LOG_LOGRADOURO_PB.TXT
  Reading LOG_LOGRADOURO_PA.TXT
  Inserted 1236944 rows into table "log_logradouro"

Populating table log_grande_usuario
  Reading LOG_GRANDE_USUARIO.TXT
  Inserted 18967 rows into table "log_grande_usuario"

Populating table log_unid_oper
  Reading LOG_UNID_OPER.TXT
  Inserted 12534 rows into table "log_unid_oper"

Populating unified CEP table
  Populating unified CEP table with logradouros data
    Inserted 1236944 CEPs from logradouros into table cep_unificado
  Populating unified CEP table with localidades data
    Inserted 4974 CEPs from localidades into table cep_unificado
  Populating unified CEP table with localidades subordinadas data
    Inserted 5311 CEPs from localidades subordinadas into table cep_unificado
  Populating unified CEP table with normalized CPC data
    Inserted 2133 CEPs from CPC into table cep_unificado
  Populating unified CEP table with normalized grandes usuários data
    Inserted 18967 CEPs from grandes usuários into table cep_unificado
  Populating unified CEP table with normalized unidades operacionais data
    Inserted 12534 CEPs from unidades operacionais into table cep_unificado
  Inserted 1280863 rows into table "cep_unificado"

Dropping tables
  Dropping table log_faixa_uop
  Dropping table log_var_log
  Dropping table log_unid_oper
  Dropping table log_num_sec
  Dropping table log_grande_usuario
  Dropping table log_var_bai
  Dropping table log_logradouro
  Dropping table log_faixa_cpc
  Dropping table log_faixa_bairro
  Dropping table log_var_loc
  Dropping table log_faixa_localidade
  Dropping table log_cpc
  Dropping table log_bairro
  Dropping table log_localidade
  Dropping table log_faixa_uf
  Dropping table ect_pais
```

#### Consulta de CEPs

Após a importação, é possível checar se os dados foram importados corretamente consultando
CEPs na tabela unificada através do comando `edne-correios-loader query-cep`. Exemplo:

```shell
$ edne-correios-loader query-cep --database-url mysql+mysqlclient://user:pass@localhost:3306/mydb 01001000
{
  "cep": "01001000",
  "logradouro": "Praça da Sé",
  "complemento": null,
  "bairro": "Sé",
  "municipio": "São Paulo",
  "municipio_cod_ibge": 3550308,
  "uf": "SP",
  "nome": null
}
```


### API Python

O `edne-correios-loader` também pode ser utilizado como uma biblioteca Python, através
do módulo `edne_correios_loader`. Exemplo:

```python
from edne_correios_loader import DneLoader, TableSetEnum

DneLoader(
  # URL de conexão com o banco de dados (obrigatório)
  'postgresql://user:pass@localhost:5432/mydb',
  # Caminho ou URL para o arquivo ZIP ou diretório com os arquivos do e-DNE (opcional) 
  dne_source="/path/to/dne.zip",
).load(
  # Quais tabelas manter no banco de dados após a importação (opcional)
  # quando omitido apenas a tabela unificada é mantida
  # Outras opções são TableSetEnum.CEP_TABLES e TableSetEnum.ALL
  table_set=TableSetEnum.CEP_TABLES
)
```

Após a importação, os CEPs podem ser consultados na tabela unificada através da classe `CepQuerier`:
```python
from edne_correios_loader import CepQuerier

cep_querier = CepQuerier('postgresql://user:pass@localhost:5432/mydb')
cep = cep_querier.query('01319010')

assert cep == {
  'cep': '79290000',
  'logradouro': None,
  'complemento': None,
  'bairro': None,
  'municipio': 'Bonito',
  'municipio_cod_ibge': 5002209,
  'uf': 'MS',
  'nome': None
}
```

## Atualização dos CEPs

Quinzenalmente os Correios atualizam o e-DNE com novos CEPs. Para atualizar sua base de dados,
execute o comando `loader` utilizando o e-DNE atualizado como fonte.

O comando irá apagar os dados de todas as tabelas do e-DNE e importar os dados do novo e-DNE.
Após a importação a tabela unificada é re-populada com os novos dados.

Todo o processo é executado em uma transação, portanto, outros clientes conectados no banco
continuarão tendo acesso aos dados antigos enquanto a atualização é executada.

Se algo der errado durante a atualização, a transação será desfeita e os dados antigos serão mantidos.


## Testes

Para executar os testes, é necessário a instalação do [Docker](https://www.docker.com/) e do
[gerenciador de projetos Python Hatch](https://github.com/pypa/hatch). Após a instalação:
1. Clone o projeto:
  ```shell
  git clone https://github.com/cauethenorio/edne-correios-loader
  ```` 
2. Rode os containers Docker com MySQL e PostgreSQL:
  ```shell
  cd edne-correios-loader/tests
  docker compose up -d
  ```
3. Execute os testes usando o `hatch`:
  ```shell
  hatch run all:test
  ``` 

## Licença

Esse projeto é distribuído sob os termos da licença [MIT](https://spdx.org/licenses/MIT.html).

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "edne-correios-loader",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "Brasil,CEP,Correios,DNE,address,eDNE,endere\u00e7o",
    "author": "",
    "author_email": "Cau\u00ea Then\u00f3rio <caue@thenorio.com.br>",
    "download_url": "https://files.pythonhosted.org/packages/71/93/0e516eba450b43d328a1beaf2310b2c9afcc8e7447a3891b5172126aa9a4/edne_correios_loader-0.1.2.tar.gz",
    "platform": null,
    "description": "# e-DNE Correios Loader\n\n[![PyPI - Version](https://img.shields.io/pypi/v/edne-correios-loader.svg)](https://pypi.org/project/edne-correios-loader)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/edne-correios-loader.svg)](https://pypi.org/project/edne-correios-loader)\n[![codecov](https://codecov.io/gh/cauethenorio/edne-correios-loader/graph/badge.svg?token=HP9C86U1LX)](https://codecov.io/gh/cauethenorio/edne-correios-loader)\n\nPrograma de linha de comando para carregar arquivos do e-DNE Basico dos Correios para um banco de\ndados (PostgreSQL, MySQL, SQLite e outros) e criar uma tabela \u00fanica para consulta de CEPs.\n\n---\n\n### [English version \ud83c\uddfa\ud83c\uddf8](README-en.md)\n\n## Funcionalidades\n\n- Carrega arquivos do DNE B\u00e1sico dos Correios para um banco de dados\n- Cria uma tabela unificada para consulta de CEPs\n- Suporta os bancos de dados PostgreSQL, MySQL, SQLite entre outros\n- Permite atualiza\u00e7\u00e3o dos dados sem interrup\u00e7\u00e3o do servi\u00e7o\n \n\n## Prop\u00f3sito\n\nO DNE (Diret\u00f3rio Nacional de Endere\u00e7os) \u00e9 um banco de dados oficial e exclusivo dos Correios,\nque cont\u00e9m mais de 900 mil CEP de todo o Brasil, constitu\u00eddo de elementos de endere\u00e7amento\n(descri\u00e7\u00e3o de logradouros, bairros, munic\u00edpios, vilas, povoados) e C\u00f3digos de Endere\u00e7amento\nPostal - CEP.\n\nEsse banco de dados \u00e9 disponibilizado em duas vers\u00f5es, o __e-DNE B\u00e1sico__ e o __e-DNE M\u00e1ster__.\nAmbas cont\u00eam todos os CEPs do Brasil, com elementos de endere\u00e7amento at\u00e9 n\u00edvel de se\u00e7\u00e3o\nde logradouro, por\u00e9m diferem no formato. O e-DNE B\u00e1sico \u00e9 composto por v\u00e1rios arquivos de texto\n(`.txt`) que precisam ser processados e transferidos para um banco de dados para poderem ser\nconsultados. J\u00e1 o e-DNE M\u00e1ster \u00e9 um banco de dados no formato MS-Access (`.mdb`) pronto para uso.\n\nO DNE \u00e9 de propriedade dos Correios e pode ser adquirido atrav\u00e9s de seu e-commerce. Atualmente\n(Outubro de 2023) a vers\u00e3o M\u00e1ster custa R$ 3.187,65 e a vers\u00e3o B\u00e1sica custa R$ 1.402,5.\nAmbas as vers\u00f5es garantem um ano de atualiza\u00e7\u00f5es ap\u00f3s a data da compra.\n\n[__Para clientes com contrato com os Correios, o e-DNE B\u00e1sico pode ser adquirido gratuitamente.__](https://www.correios.com.br/enviar/marketing-direto/saiba-mais-nacional)\n\nEsse projeto facilita o uso do e-DNE B\u00e1sico, que \u00e9 mais barato e mais f\u00e1cil de ser adquirido,\nprocessando os arquivos de texto e transferindo-os para um banco de dados, ele tamb\u00e9m cria uma\ntabela \u00fanica para consulta de CEPs (n\u00e3o inclusa no DNE, onde CEPs de diferentes tipos ficam em\ntabelas diferentes) e permite que sua base seja atualizada com novas vers\u00f5es do e-DNE, lan\u00e7adas\nquinzenalmente pelos Correios.\n\n\n## Instala\u00e7\u00e3o\n\nO `edne-correios-loader` pode ser instalado atrav\u00e9s do `pip`:\n\n```shell\npip install edne-correios-loader\n```\n\nTamb\u00e9m ser\u00e1 necess\u00e1rio instalar o driver do banco de dados que ser\u00e1 utilizado. Aqui est\u00e3o algumas\ninstru\u00e7\u00f5es de como instalar os drivers para os bancos de dados mais comuns:\n\n### PostgreSQL\n\nPara o PostgreSQL, o driver `psycopg2-binary` pode ser instalado utilizando um\n[extra](https://peps.python.org/pep-0508/#extras):\n```shell\npip install edne-correios-loader[postgresql]\n```\n\nSe n\u00e3o houver uma vers\u00e3o compilada do `psycopg2` para seu sistema operacional e vers\u00e3o do python,\nvoc\u00ea precisar\u00e1 instalar algumas bibliotecas para poder compilar o driver. Outra op\u00e7\u00e3o \u00e9 instalar o\ndriver `pg8000` para o PostgreSQL, que \u00e9 escrito totalmente em Python e n\u00e3o precisa ser compilado.\n\n### MySQL\n\nPara o MySQL, o driver `mysqlclient` pode ser instalado utilizando um\n[extra](https://peps.python.org/pep-0508/#extras):\n```shell\npip install edne-correios-loader[mysql]\n```\n\n### SQLite\n\nO Python j\u00e1 disponibiliza a biblioteca `sqlite3` para comunica\u00e7\u00e3o com o SQLite, portanto n\u00e3o \u00e9\nnecess\u00e1ria nenhuma instru\u00e7\u00e3o adicional.\n\n### Outros\n\nA biblioteca `sqlalchemy` \u00e9 utilizada para comunica\u00e7\u00e3o com o banco de dados, portanto qualquer banco\nde dados suportado por ela pode ser utilizado, como o Microsoft SQL Server e Oracle. Para instalar\no driver de um banco de dados n\u00e3o listado aqui, consulte a documenta\u00e7\u00e3o do SQLAlchemy:\nhttps://docs.sqlalchemy.org/en/20/dialects/index.html\n\n\n## Utiliza\u00e7\u00e3o\n\n### Linha de comando\n\nA importa\u00e7\u00e3o dos dados pode ser executada atrav\u00e9s da linha de comando, com o\ncomando `edne-correios-loader load`.\n\n```shell\n$ edne-correios-loader load --help\n\nUsage: edne-correios-loader load [OPTIONS]\n\n  Load DNE data into a database.\n\nOptions:\n  -s, --dne-source <path/zip-file/url>\n                                  Path or URL with the DNE file/dir to be\n                                  imported\n  -db, --database-url <url>       Database URL where the DNE data will be\n                                  imported to  [required]\n  --tables [unified-cep-only|cep-tables|all]\n                                  Which tables to keep in the database after\n                                  the import\n  -v, --verbose                   Enables verbose mode.\n  -h, --help                      Show this message and exit.\n```\n\n#### Op\u00e7\u00f5es\n\nAs seguintes op\u00e7\u00f5es est\u00e3o dispon\u00edveis:\n- __`--dne-source`__ **(opcional)**\n\n  Origem do e-DNE a ser importado. Pode ser:\n    - Uma URL apontando para um arquivo ZIP com o e-DNE\n    - O caminho local para um arquivo ZIP com o e-DNE\n    - O caminho local para um diret\u00f3rio contendo os arquivos do e-DNE\n    \n  Se essa opc\u00e3o n\u00e3o for informada, o \u00faltimo e-DNE B\u00e1sico dispon\u00edvel no site dos\n  Correios ser\u00e1 baixado e usado como fonte. **Utilize essa op\u00e7\u00e3o apenas se voc\u00ea\n  tiver um contrato com os Correios**.\n \n\n- __`--database-url`__ **(obrigat\u00f3rio)**\n\n  URL do banco de dados onde os dados do e-DNE ser\u00e3o importados. A URL deve seguir o\n  padr\u00e3o `dialect+driver://username:password@host:port/database`, onde:\n    - `dialect` \u00e9 o nome do banco de dados, como `postgresql`, `mysql`, `sqlite`, etc.\n    - `driver` \u00e9 o nome do driver do banco de dados, como `psycopg2`, `mysqlclient`,\n      `pg8000`, etc. Se n\u00e3o especificado, o driver mais popular \u00e9 utilizado automaticamente.\n    - `username` \u00e9 o nome de usu\u00e1rio do banco de dados\n    - `password` \u00e9 a senha do usu\u00e1rio do banco de dados\n    - `host` \u00e9 o endere\u00e7o do servidor do banco de dados\n    - `port` \u00e9 a porta do servidor do banco de dados\n    - `database` \u00e9 o nome do banco de dados\n\n  Mais informa\u00e7\u00f5es sobre o formato da URL podem ser encontradas na documenta\u00e7\u00e3o do\n    [SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)\n \n\n- __`--tables`__ **(opcional)**\n\n  Define quais tabelas ser\u00e3o mantidas no banco de dados ap\u00f3s a importa\u00e7\u00e3o. Pode ser:\n    - `unified-cep-only`: Mant\u00e9m apenas a tabela unificada de CEPs\n    - `cep-tables`: Mant\u00e9m apenas as tabelas com CEPs, separadas por tipo\n    - `all`: Mant\u00e9m todas as tabelas do DNE\n\n  Quando n\u00e3o especificado, a op\u00e7\u00e3o `unified-cep-only` \u00e9 utilizada por padr\u00e3o, mantendo\n  apenas a tabela unificada de CEPs.\n\n\n- __`--verbose`__ **(opcional)**\n\n  Habilita o modo verboso, que exibe informa\u00e7\u00f5es de DEBUG \u00fateis para resolver problemas\n  na execu\u00e7\u00e3o do comando\n\n#### Exemplos de uso\n\nImporta o e-DNE B\u00e1sico direto do site dos correios para um banco de dados SQLite local,\nmantendo apenas a tabela unificada:\n```shell\nedne-correios-loader load --database-url sqlite:///dne.db\n```\n\nImporta o e-DNE B\u00e1sico de um arquivo ZIP para um banco de dados PostgreSQL local, mantendo\ntodas as tabelas com CEPs:\n```shell\nedne-correios-loader load \\\n  --dne-source /path/to/dne.zip \\\n  --database-url postgresql://user:pass@localhost:5432/mydb \\\n  --tables cep-tables\n```\n\nImporta o e-DNE B\u00e1sico de um diret\u00f3rio para um banco de dados MySQL local, mantendo todas\nas tabelas:\n```shell\nedne-correios-loader load \\\n  --dne-source /path/to/dne/dir \\\n  --database-url mysql+mysqlclient://user:pass@localhost:3306/mydb \\\n  --tables all\n```\n\nO output do comando deve variar conforme as op\u00e7\u00f5es utilizadas, mas deve ser\nparecido com o seguinte:\n```\nStarting DNE Correios Loader v0.1.1\n\nConnecting to database...\n\nResolving DNE source...\n\nNo DNE source provided, the latest DNE will be downloaded from Correios website\nDownloading DNE file  [####################################]  100%\n\nCreating tables:\n- cep_unificado\n- log_localidade\n- log_bairro\n- log_cpc\n- log_logradouro\n- log_grande_usuario\n- log_unid_oper\n\nCleaning tables\n\nPopulating table log_localidade\n  Reading LOG_LOCALIDADE.TXT\n  Inserted 11219 rows into table \"log_localidade\"\n\nPopulating table log_bairro\n  Reading LOG_BAIRRO.TXT\n  Inserted 64456 rows into table \"log_bairro\"\n\nPopulating table log_cpc\n  Reading LOG_CPC.TXT\n  Inserted 2133 rows into table \"log_cpc\"\n\nPopulating table log_logradouro\n  Reading LOG_LOGRADOURO_RS.TXT\n  Reading LOG_LOGRADOURO_RR.TXT\n  Reading LOG_LOGRADOURO_SC.TXT\n  Reading LOG_LOGRADOURO_SP.TXT\n  Reading LOG_LOGRADOURO_SE.TXT\n  Reading LOG_LOGRADOURO_PI.TXT\n  Reading LOG_LOGRADOURO_MS.TXT\n  Reading LOG_LOGRADOURO_AP.TXT\n  Reading LOG_LOGRADOURO_MG.TXT\n  Reading LOG_LOGRADOURO_MT.TXT\n  Reading LOG_LOGRADOURO_AC.TXT\n  Reading LOG_LOGRADOURO_MA.TXT\n  Reading LOG_LOGRADOURO_TO.TXT\n  Reading LOG_LOGRADOURO_AL.TXT\n  Reading LOG_LOGRADOURO_CE.TXT\n  Reading LOG_LOGRADOURO_BA.TXT\n  Reading LOG_LOGRADOURO_AM.TXT\n  Reading LOG_LOGRADOURO_ES.TXT\n  Reading LOG_LOGRADOURO_PR.TXT\n  Reading LOG_LOGRADOURO_PE.TXT\n  Reading LOG_LOGRADOURO_GO.TXT\n  Reading LOG_LOGRADOURO_RN.TXT\n  Reading LOG_LOGRADOURO_RO.TXT\n  Reading LOG_LOGRADOURO_DF.TXT\n  Reading LOG_LOGRADOURO_RJ.TXT\n  Reading LOG_LOGRADOURO_PB.TXT\n  Reading LOG_LOGRADOURO_PA.TXT\n  Inserted 1236944 rows into table \"log_logradouro\"\n\nPopulating table log_grande_usuario\n  Reading LOG_GRANDE_USUARIO.TXT\n  Inserted 18967 rows into table \"log_grande_usuario\"\n\nPopulating table log_unid_oper\n  Reading LOG_UNID_OPER.TXT\n  Inserted 12534 rows into table \"log_unid_oper\"\n\nPopulating unified CEP table\n  Populating unified CEP table with logradouros data\n    Inserted 1236944 CEPs from logradouros into table cep_unificado\n  Populating unified CEP table with localidades data\n    Inserted 4974 CEPs from localidades into table cep_unificado\n  Populating unified CEP table with localidades subordinadas data\n    Inserted 5311 CEPs from localidades subordinadas into table cep_unificado\n  Populating unified CEP table with normalized CPC data\n    Inserted 2133 CEPs from CPC into table cep_unificado\n  Populating unified CEP table with normalized grandes usu\u00e1rios data\n    Inserted 18967 CEPs from grandes usu\u00e1rios into table cep_unificado\n  Populating unified CEP table with normalized unidades operacionais data\n    Inserted 12534 CEPs from unidades operacionais into table cep_unificado\n  Inserted 1280863 rows into table \"cep_unificado\"\n\nDropping tables\n  Dropping table log_faixa_uop\n  Dropping table log_var_log\n  Dropping table log_unid_oper\n  Dropping table log_num_sec\n  Dropping table log_grande_usuario\n  Dropping table log_var_bai\n  Dropping table log_logradouro\n  Dropping table log_faixa_cpc\n  Dropping table log_faixa_bairro\n  Dropping table log_var_loc\n  Dropping table log_faixa_localidade\n  Dropping table log_cpc\n  Dropping table log_bairro\n  Dropping table log_localidade\n  Dropping table log_faixa_uf\n  Dropping table ect_pais\n```\n\n#### Consulta de CEPs\n\nAp\u00f3s a importa\u00e7\u00e3o, \u00e9 poss\u00edvel checar se os dados foram importados corretamente consultando\nCEPs na tabela unificada atrav\u00e9s do comando `edne-correios-loader query-cep`. Exemplo:\n\n```shell\n$ edne-correios-loader query-cep --database-url mysql+mysqlclient://user:pass@localhost:3306/mydb 01001000\n{\n  \"cep\": \"01001000\",\n  \"logradouro\": \"Pra\u00e7a da S\u00e9\",\n  \"complemento\": null,\n  \"bairro\": \"S\u00e9\",\n  \"municipio\": \"S\u00e3o Paulo\",\n  \"municipio_cod_ibge\": 3550308,\n  \"uf\": \"SP\",\n  \"nome\": null\n}\n```\n\n\n### API Python\n\nO `edne-correios-loader` tamb\u00e9m pode ser utilizado como uma biblioteca Python, atrav\u00e9s\ndo m\u00f3dulo `edne_correios_loader`. Exemplo:\n\n```python\nfrom edne_correios_loader import DneLoader, TableSetEnum\n\nDneLoader(\n  # URL de conex\u00e3o com o banco de dados (obrigat\u00f3rio)\n  'postgresql://user:pass@localhost:5432/mydb',\n  # Caminho ou URL para o arquivo ZIP ou diret\u00f3rio com os arquivos do e-DNE (opcional) \n  dne_source=\"/path/to/dne.zip\",\n).load(\n  # Quais tabelas manter no banco de dados ap\u00f3s a importa\u00e7\u00e3o (opcional)\n  # quando omitido apenas a tabela unificada \u00e9 mantida\n  # Outras op\u00e7\u00f5es s\u00e3o TableSetEnum.CEP_TABLES e TableSetEnum.ALL\n  table_set=TableSetEnum.CEP_TABLES\n)\n```\n\nAp\u00f3s a importa\u00e7\u00e3o, os CEPs podem ser consultados na tabela unificada atrav\u00e9s da classe `CepQuerier`:\n```python\nfrom edne_correios_loader import CepQuerier\n\ncep_querier = CepQuerier('postgresql://user:pass@localhost:5432/mydb')\ncep = cep_querier.query('01319010')\n\nassert cep == {\n  'cep': '79290000',\n  'logradouro': None,\n  'complemento': None,\n  'bairro': None,\n  'municipio': 'Bonito',\n  'municipio_cod_ibge': 5002209,\n  'uf': 'MS',\n  'nome': None\n}\n```\n\n## Atualiza\u00e7\u00e3o dos CEPs\n\nQuinzenalmente os Correios atualizam o e-DNE com novos CEPs. Para atualizar sua base de dados,\nexecute o comando `loader` utilizando o e-DNE atualizado como fonte.\n\nO comando ir\u00e1 apagar os dados de todas as tabelas do e-DNE e importar os dados do novo e-DNE.\nAp\u00f3s a importa\u00e7\u00e3o a tabela unificada \u00e9 re-populada com os novos dados.\n\nTodo o processo \u00e9 executado em uma transa\u00e7\u00e3o, portanto, outros clientes conectados no banco\ncontinuar\u00e3o tendo acesso aos dados antigos enquanto a atualiza\u00e7\u00e3o \u00e9 executada.\n\nSe algo der errado durante a atualiza\u00e7\u00e3o, a transa\u00e7\u00e3o ser\u00e1 desfeita e os dados antigos ser\u00e3o mantidos.\n\n\n## Testes\n\nPara executar os testes, \u00e9 necess\u00e1rio a instala\u00e7\u00e3o do [Docker](https://www.docker.com/) e do\n[gerenciador de projetos Python Hatch](https://github.com/pypa/hatch). Ap\u00f3s a instala\u00e7\u00e3o:\n1. Clone o projeto:\n  ```shell\n  git clone https://github.com/cauethenorio/edne-correios-loader\n  ```` \n2. Rode os containers Docker com MySQL e PostgreSQL:\n  ```shell\n  cd edne-correios-loader/tests\n  docker compose up -d\n  ```\n3. Execute os testes usando o `hatch`:\n  ```shell\n  hatch run all:test\n  ``` \n\n## Licen\u00e7a\n\nEsse projeto \u00e9 distribu\u00eddo sob os termos da licen\u00e7a [MIT](https://spdx.org/licenses/MIT.html).\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "Load Brazilian Correios' e-DNE Basico text files into your database to enable CEP search",
    "version": "0.1.2",
    "project_urls": {
        "Documentation": "https://github.com/cauethenorio/edne-correios-loader#readme",
        "Issues": "https://github.com/cauethenorio/edne-correios-loader/issues",
        "Source": "https://github.com/cauethenorio/edne-correios-loader"
    },
    "split_keywords": [
        "brasil",
        "cep",
        "correios",
        "dne",
        "address",
        "edne",
        "endere\u00e7o"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "54fcd69a2297ba506b88a40c609a3eb294ff9c4955ae22c5b2cdbb45cb83354d",
                "md5": "770e5afb26afab4d4e3b0902c048a268",
                "sha256": "6e07c907aa8c12dbeef39fd3cb763c09ea8a71cada2f33220d2d22b6875aa9b2"
            },
            "downloads": -1,
            "filename": "edne_correios_loader-0.1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "770e5afb26afab4d4e3b0902c048a268",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 22381,
            "upload_time": "2023-10-11T17:19:01",
            "upload_time_iso_8601": "2023-10-11T17:19:01.479461Z",
            "url": "https://files.pythonhosted.org/packages/54/fc/d69a2297ba506b88a40c609a3eb294ff9c4955ae22c5b2cdbb45cb83354d/edne_correios_loader-0.1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "71930e516eba450b43d328a1beaf2310b2c9afcc8e7447a3891b5172126aa9a4",
                "md5": "577bfdab7d519ca0364883b5633df3dc",
                "sha256": "62b9c3a899d565bd4b9008ec951ea7f26906c316aaab67276355f1dd5834c9a2"
            },
            "downloads": -1,
            "filename": "edne_correios_loader-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "577bfdab7d519ca0364883b5633df3dc",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 24746,
            "upload_time": "2023-10-11T17:19:03",
            "upload_time_iso_8601": "2023-10-11T17:19:03.307586Z",
            "url": "https://files.pythonhosted.org/packages/71/93/0e516eba450b43d328a1beaf2310b2c9afcc8e7447a3891b5172126aa9a4/edne_correios_loader-0.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-10-11 17:19:03",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "cauethenorio",
    "github_project": "edne-correios-loader#readme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "edne-correios-loader"
}
Elapsed time: 0.12274s