Package: edne-correios-loader
e-DNE Correios LoaderPrograma 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 🇺🇸FuncionalidadesCarrega arquivos do DNE Básico dos Correios para um banco de dadosCria uma tabela unificada para consulta de CEPsSuporta os bancos de dados PostgreSQL, MySQL, SQLite entre outrosPermite atualização dos dados sem interrupção do serviçoPropósitoO 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, oe-DNE Básicoe oe-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.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çãoOedne-correios-loaderpode ser instalado através dopip:pipinstalledne-correios-loaderTambé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:PostgreSQLPara o PostgreSQL, o driverpsycopg2-binarypode ser instalado utilizando umextra:pipinstalledne-correios-loader[postgresql]Se não houver uma versão compilada dopsycopg2para seu sistema operacional e versão do python,
você precisará instalar algumas bibliotecas para poder compilar o driver. Outra opção é instalar o
driverpg8000para o PostgreSQL, que é escrito totalmente em Python e não precisa ser compilado.MySQLPara o MySQL, o drivermysqlclientpode ser instalado utilizando umextra:pipinstalledne-correios-loader[mysql]SQLiteO Python já disponibiliza a bibliotecasqlite3para comunicação com o SQLite, portanto não é
necessária nenhuma instrução adicional.OutrosA bibliotecasqlalchemyé 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.htmlUtilizaçãoLinha de comandoA importação dos dados pode ser executada através da linha de comando, com o
comandoedne-correios-loader load.$edne-correios-loaderload--help

Usage:edne-correios-loaderload[OPTIONS]LoadDNEdataintoadatabase.

Options:-s,--dne-source<path/zip-file/url>PathorURLwiththeDNEfile/dirtobeimported-db,--database-url<url>DatabaseURLwheretheDNEdatawillbeimportedto[required]--tables[unified-cep-only|cep-tables|all]Whichtablestokeepinthedatabaseaftertheimport-v,--verboseEnablesverbosemode.-h,--helpShowthismessageandexit.OpçõesAs 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-DNEO caminho local para um arquivo ZIP com o e-DNEO caminho local para um diretório contendo os arquivos do e-DNESe 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ãodialect+driver://username:password@host:port/database, onde:dialecté o nome do banco de dados, comopostgresql,mysql,sqlite, etc.driveré o nome do driver do banco de dados, comopsycopg2,mysqlclient,pg8000, etc. Se não especificado, o driver mais popular é utilizado automaticamente.usernameé o nome de usuário do banco de dadospasswordé a senha do usuário do banco de dadoshosté o endereço do servidor do banco de dadosporté a porta do servidor do banco de dadosdatabaseé o nome do banco de dadosMais informações sobre o formato da URL podem ser encontradas na documentação doSQLAlchemy--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 CEPscep-tables: Mantém apenas as tabelas com CEPs, separadas por tipoall: Mantém todas as tabelas do DNEQuando não especificado, a opçãounified-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 comandoExemplos de usoImporta o e-DNE Básico direto do site dos correios para um banco de dados SQLite local,
mantendo apenas a tabela unificada:edne-correios-loaderload--database-urlsqlite:///dne.dbImporta o e-DNE Básico de um arquivo ZIP para um banco de dados PostgreSQL local, mantendo
todas as tabelas com CEPs:edne-correios-loaderload\--dne-source/path/to/dne.zip\--database-urlpostgresql://user:pass@localhost:5432/mydb\--tablescep-tablesImporta o e-DNE Básico de um diretório para um banco de dados MySQL local, mantendo todas
as tabelas:edne-correios-loaderload\--dne-source/path/to/dne/dir\--database-urlmysql+mysqlclient://user:pass@localhost:3306/mydb\--tablesallO 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_paisConsulta de CEPsApós a importação, é possível checar se os dados foram importados corretamente consultando
CEPs na tabela unificada através do comandoedne-correios-loader query-cep. Exemplo:$edne-correios-loaderquery-cep--database-urlmysql+mysqlclient://user:pass@localhost:3306/mydb01001000{"cep":"01001000","logradouro":"Praça da Sé","complemento":null,"bairro":"Sé","municipio":"São Paulo","municipio_cod_ibge":3550308,"uf":"SP","nome":null}API PythonOedne-correios-loadertambém pode ser utilizado como uma biblioteca Python, através
do móduloedne_correios_loader. Exemplo:fromedne_correios_loaderimportDneLoader,TableSetEnumDneLoader(# 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.ALLtable_set=TableSetEnum.CEP_TABLES)Após a importação, os CEPs podem ser consultados na tabela unificada através da classeCepQuerier:fromedne_correios_loaderimportCepQueriercep_querier=CepQuerier('postgresql://user:pass@localhost:5432/mydb')cep=cep_querier.query('01319010')assertcep=={'cep':'79290000','logradouro':None,'complemento':None,'bairro':None,'municipio':'Bonito','municipio_cod_ibge':5002209,'uf':'MS','nome':None}Atualização dos CEPsQuinzenalmente os Correios atualizam o e-DNE com novos CEPs. Para atualizar sua base de dados,
execute o comandoloaderutilizando 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.TestesPara executar os testes, é necessário a instalação doDockere dogerenciador de projetos Python Hatch. Após a instalação:Clone o projeto:gitclonehttps://github.com/cauethenorio/edne-correios-loaderRode os containers Docker com MySQL e PostgreSQL:cdedne-correios-loader/tests
dockercomposeup-dExecute os testes usando ohatch:hatchrunall:testLicençaEsse projeto é distribuído sob os termos da licençaMIT.