dpckan 0.1.22

Funções para gestão de pacotes de dados no portal dados.mg.gov.br

Data package manager para CKAN (dpckan)

O dpckan é um pacote Python, acessível via interface CLI, utilizado para criação e atualização de conjuntos de dados e recursos (documentados de acordo com o padrão de metadados Frictionless Data) em uma instância do CKAN.

Curiosidades: Consulte a comparação do dpckan com alguns projetos relacionados.

Documentação complementar

Instalação

O dpckan está disponível no Python Package Index - PyPI e pode ser instalado utilizando-se o comando abaixo:

# Antes de executar o comando abaixo lembre-se que ambiente Python deverá estar ativo
$ pip install dpckan

Configuração de Variáveis de ambiente

Todos os comandos exigem a indicação de uma instância CKAN (ex: https://demo.ckan.org/) e de uma chave válida para autenticação na referida instância. Esta indicação deverá ser realizada através do cadastro de variáveis de ambiente. Para invocação CLI de qualquer comando sem a necessidade de indicar explicitamente estas variáveis recomenda-se utilização dos nomes CKAN_HOST e CKAN_KEY para cadastro de instância e chave respectivamente. Caso outros nomes sejam utilizados, necessário indicar explicitamente durante a chamada da função desejada, utilizando-se as flags "--ckan-host" e "--ckan-key", conforme demostrado abaixo e ou de maneira mais detalhada na sessão Uso.

# CKAN_HOST=https://demo.ckan.org/
# CKAN_KEY=CC850181-6ZS9-4f4C-bf3f-fb4db7ce09f90 (Chave CKAN meramente ilustrativa)
# Utilização sem necessidade de indicar explicitamente variáveis

$ dpckan dataset create

# CKAN_HOST_PRODUCAO=https://demo.ckan.org/
# CKAN_KEY_PRODUCAO=CC850181-6ZS9-4f4C-bf3f-fb4db7ce09f90 (Chave CKAN meramente ilustrativa)
# Utilização indicando explicitamente variáveis, através flags --ckan-host e --ckan-key

$ dpckan --ckan-host $CKAN_HOST_PRODUCAO --ckan-key $CKAN_KEY_PRODUCAO dataset create

O cadastro das variáveis de ambiente CKAN_HOST e CKAN_KEY, necessárias para invocação de cada comando, deverá ser realizada conforme sistema operacional do usuário. Abaixo links de referência para tal:

• Windows
• Linux
• Mac

Alternativamente, o cadastro destas variáveis de ambiente poderá ser realizado em arquivo ".env", na raiz do conjunto de dados, sendo necessário a inclusão deste ".env" em arquivo ".gitignore", evitando assim a sincronização e consequente publicização destas chaves em repositórios online como github, conforme demostrado abaixo:

# CUIDADO: SOMENTE UTILIZE A OPÇÃO SUGERIDA ABAIXO SE POSSUIR FAMILIARIDADE COM O ASSUNTO, EVITANDO ASSIM PROBLEMAS COM ACESSO DE TERCEIROS NÃO AUTORIZADOS EM SUA INSTÂNCIA CKAN
# CUIDADO: SOMENTE EXECUTE OS COMANDOS ABAIXO SE OS ARQUIVO ".env" e ".gitignore" NÃO EXISTIREM NA RAIZ DO CONJUNTO DE DADOS
# CUIDADO: CASO COMANDOS ABAIXO SEJAM EXECUTADOS COM ".env" e ".gitignore" EXISTENTES TODO CONTEÚDO DOS MESMOS SERÁ APAGADO

# Crie arquivo ".env" com estrutura para receber chaves CKAN_HOST e CKAN_KEY
# Após a criação, abra o arquivo e inclua os valores para cada variável

$ echo "CKAN_HOST=''\nCKAN_KEY=''" > .env

# Crie arquivo ".gitignore" com configuração para excluir arquivo ".env" do controle de versão git

$ echo ".env" > .gitignore

# Confira se configuração foi realizada com sucesso
# Comando abaixo deverá mostrar apenas criação/modificação de arquivo ".gitignore", não sendo apresentado nada para arquivo ".env"

$ git status

Uso

• Antes de executar cada comando verifique:
  • Se as variáveis de ambiente estão definidas corretamente;
  • O local aonde os comandos serão executados, pois a execução no mesmo diretório do arquivo datapackage.json simplificará o trabalho;
  • Não copie e cole os comandos sugeridos abaixo cegamente, indicações entre "<>" sevirão para ilustrar variáveis a serem adequadas para a realidade do usuário.

Acessando documentação do dpckan via terminal

# Informações gerais sobre o pacote e seus comandos
$ dpckan --help

# Informações sobre comandos dataset e resource
$ dpckan dataset --help
$ dpckan resource --help

# Informações sobre sub-comandos dataset
$ dpckan dataset create --help
$ dpckan dataset update --help

# Informações sobre sub-comandos resource
$ dpckan resource create --help
$ dpckan resource update --help

Interrompendo execução em caso de erros de validação frictionless

Durante a execução dos comandos dpckan a biblioteca frictionless será utilizada para validação local do conjunto de dados via frictionless validate. Erros durante esta validação serão informados ao usuário mas somente interromperão a execução se a flag --stop for passada como parâmetro, conforme demonstrado abaixo:

$ dpckan dataset create --stop

Baixando conjuntos de dados publicados em instância CKAN

• Para baixar um conjunto de dados publicado em alguma instância do CKAN utilize o comando abaixo:

$ dpckan dataset get --dataset-id dataset-link

Criando e atualizando um conjunto de dados via terminal

Para criar um conjunto de dados, execute o comando no diretório aonde o arquivo datapackage.json se encontra:

$ dpckan dataset create

E para atualizar o conjunto de dados, execute o comando no diretório aonde o arquivo datapackage.json se encontra:

$ dpckan dataset update

CUIDADO: A atualização de conjunto de dados presupõe:

• Criação do conjunto de dados via comando dpckan dataset create;
• Criação de recursos via comando dpckan resource create; e
• Igualdade entre o número e nome dos recursos locais e da instância CKAN.

Criando e atualizando recursos via terminal

CUIDADO: Recursos com nomes iguais além de desrespeitar a especificação frictionless confundem o usuário.

Para criar um recurso, execute o seguinte comando no diretório aonde o arquivo datapackage.json se encontra.

$ dpckan resource <nome-recurso> create

Para atualizar um recurso, execute o seguinte comando no diretório aonde o arquivo datapackage.json se encontra.

$ dpckan resource <nome-recurso> <id-recurso> update

Em ambiente de homologação cadastrado na máquina,

$ dpckan --ckan-host $HOMOLOGA_HOST --ckan-key $HOMOLOGA_KEY resource <nome_recurso> create

ou

$ dpckan --ckan-host $HOMOLOGA_HOST --ckan-key $HOMOLOGA_KEY resource <nome_recurso> <id-recurso> update

para atualizar

Contribuições

Pré-requisitos: Python 3.9 ou superior

Documentação de referência mostrando procedimentos necessários para contribuição em um projeto open source

• Passos básicos:
  • Crie um fork do repositório do projeto;
  • Clone o repositório criado em seu github após o fork;
  • Navegue até o repositório clonado em sua máquina;
  • Crie e ative um ambiente virtual Python para utilizar o projeto;
  • Crie um branch para realizar as modificações necessárias;
  • Realize o push da branch criada; e
  • Abra um PR explicando os motivos da mudança e como esta auxiliará no desenvolvimento do projeto.

Atualizar versão

Conforme relatado no issue 6, atualização de versões no Pypi deve seguir estes os passos

Licença

O dpckan é licenciado sob a licença MIT. Veja o arquivo LICENSE.md para mais detalhes.

Change Log

0.1.22 (29/08/2023)

• Melhora processo de criação/atualização datastore

0.1.21 (07/03/2023)

• Possibilita atualização de conjuntos privados

0.1.20 (16/02/2023)

• Fixa versões de pacotes dependentes - erro de atualização versão frictionless 5

0.1.19 (22/11/2022)

• Melhora mensagens de log informando qual host está sendo utilizado

0.1.18 (02/04/2022)

• Adiciona flag --exit-code
• Bug Fix na chamada da função dataset update que não estava atualizando metadados do conjunto

0.1.17 (14/03/2022)

• Bug Fix na chamada da função resource_update dentro de dataset_update

0.1.16 (14/03/2022)

• Inclusão função dpckan dataset get
• Correções flag --datastore
• Correções dpckan resource create

0.1.15 (21/02/2021)

• Registra ids de recursos publicados apenas na instância CKAN e não mais no arquivo datapackage.json local
• Revisa/simplifica documentação CLI
• Modifica chamada das funções

0.1.14 (27/12/2021)

• Corrige funcionamento da flag para acionamento do datastore nunca produzir efeitos
• Altera nome da flag para acionamento do datastore durante criação e atualização de conjunto de dados de metadata para datastore

0.1.13 (22/12/2021)

• Remove extended do nome do arquivo extended_datapackage.json durante criação de recursos datapackage.json

0.1.12 (21/12/2021)

• Adiciona Flag metadata para acionamento datastore durante criação e atualização de conjunto de dados

0.1.11 (01/12/2021)

• Adicionando encoding para subir arquivos README, CONTRIBUTING e CHANGELOG para CKAN
• Atualizando metadado do conjunto caso apenas datapackage.json sofra modificações

0.1.10 (12/11/2021)

• Dataset update primeira versão, atualizando recursos e metadados modificados
• Pequenas refatorações

0.1.9 (12/11/2021)

• Correção pacote ipdb importado erradamente

0.1.8 (12/11/2021)

• Apaga propriedade ckan_hosts apenas da instância CKAN desejada
• Expansão schema e dialetic presentes no recurso datapackage.json importados na instância CKAN

0.1.7 (11/11/2021)

• Melhoria da implementação da documentação do conjunto de dados publicados no CKAN

0.1.6 (11/11/2021)

• Validando a existência da proprieda owner_org do arquivo datapackage.json
• Validando a existência do valor da propriedade owner_org do arquivo datapackage.json na instância do CKAN desejada

0.1.5 (11/11/2021)

• Melhoria de documentação click (--help)
• Inclusão de flag --stop para interromper execução em caso de falha de validação frictionless

0.1.4 (08/11/2021)

• Separação pacotes de desenvolvimento (requirements.txt) de pacotes de utilização (setup.py)
• Inclusão frictionless validate como validações

0.1.3 (20/10/2021)

• Erro de publicação desta versão

0.1.2 (20/10/2021)

• Update python-dotenv

0.1.1 (08/09/2021)

• Revisão documentação README.md
• Revisão documentação docstrings
• Revisão estrutura testes

0.1.0 (23/08/2021)

• Criação dos comandos cli para criação e atualização de datasets
• Criação dos comandos cli para criação e atualização de recursos
• Melhoria da documentação

0.0.1.9020 (09/06/2021)

• Publicação de documentação online do pacote
• Correção de bugs e exclusão de códigos repetidos ao longo do projeto

0.0.1.9000 (06/05/2021)

• Lançamento primeira versão de teste do pacote