# e-DNE Correios Loader
[](https://pypi.org/project/edne-correios-loader)
[](https://pypi.org/project/edne-correios-loader)
[](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": null,
"name": "edne-correios-loader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Brasil, CEP, Correios, DNE, address, eDNE, endere\u00e7o",
"author": null,
"author_email": "Cau\u00ea Then\u00f3rio <caue@thenorio.com.br>",
"download_url": "https://files.pythonhosted.org/packages/c5/a9/4a4720f9ec19d41e5189c958ef117d7543a1daa58560769eb9fc5d8f9274/edne_correios_loader-0.1.3.tar.gz",
"platform": null,
"description": "# e-DNE Correios Loader\n\n[](https://pypi.org/project/edne-correios-loader)\n[](https://pypi.org/project/edne-correios-loader)\n[](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": null,
"summary": "Load Brazilian Correios' e-DNE Basico text files into your database to enable CEP search",
"version": "0.1.3",
"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": "e74f1568315ba718f708dc6c01ff6303e6ad617b8710efd9893d2f589b5006dd",
"md5": "fc73c6764301b8742ac4544e88179909",
"sha256": "76ab64036a6da10bc061b1d58afc12121fe523206b679164bfee87894ca6c8a0"
},
"downloads": -1,
"filename": "edne_correios_loader-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc73c6764301b8742ac4544e88179909",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22378,
"upload_time": "2024-06-03T03:38:57",
"upload_time_iso_8601": "2024-06-03T03:38:57.392327Z",
"url": "https://files.pythonhosted.org/packages/e7/4f/1568315ba718f708dc6c01ff6303e6ad617b8710efd9893d2f589b5006dd/edne_correios_loader-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5a94a4720f9ec19d41e5189c958ef117d7543a1daa58560769eb9fc5d8f9274",
"md5": "9b4ee92e1b0a23f4ca2bd419a5b8ce69",
"sha256": "0d326e41c9585b7f3b1b63a30cc48a6fdf8c4e1cbeb53cd2f40e087612f731b9"
},
"downloads": -1,
"filename": "edne_correios_loader-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "9b4ee92e1b0a23f4ca2bd419a5b8ce69",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24802,
"upload_time": "2024-06-03T03:38:58",
"upload_time_iso_8601": "2024-06-03T03:38:58.751360Z",
"url": "https://files.pythonhosted.org/packages/c5/a9/4a4720f9ec19d41e5189c958ef117d7543a1daa58560769eb9fc5d8f9274/edne_correios_loader-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-03 03:38:58",
"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"
}
JSON
