Skip to main content

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

Project description

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 dataset create --ckan-host $CKAN_HOST_PRODUCAO --ckan-key $CKAN_KEY_PRODUCAO

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:

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:

# 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
# CUIDADO: SOMENTE EXECUTE OS COMANDOS ABAIXO SE TIVER CERTEZA E CONHECIMENTO DO QUE SERÁ FEITO

# 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

AVISO: VERIFIQUE AS VARIÁVEIS DE AMBIENTE E O CAMINHO DOS ARQUIVOS ANTES DE EXECUTAR CADA COMANDO. NÃO COPIE E COLE O CÓDIGO CEGAMENTE!

Acessando documentação do dpckan via terminal

# Informações gerais sobre o pacote e seus comandos
# Utilização das flags --help ou -h retornará o mesmo resultado
$ dpckan

# Informações sobre comandos dataset e resource
# Utilização das flags --help ou -h retornará o mesmo resultado
$ dpckan dataset
$ dpckan resource

# Informações sobre subcomandos dataset
# Utilização da flag -h retornará o mesmo resultado
$ dpckan dataset create --help
$ dpckan dataset update --help

# Informações sobre subcomandos resource
# Utilização da flag -h retornará o mesmo resultado
$ dpckan resource create --help
$ dpckan resource update --help

Criando e atualizando com 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

Criando e atualizando recursos via terminal

  • Para criar um recurso, execute o seguinte comando no diretório aonde o arquivo datapackage.json se encontra. Não se esqueça de modificar o último argumento com o nome do recurso presente no arquivo datapackage.json que será criado
$ dpckan resource create --resource-name nome-recurso

# Utilização alias -rn para flag --resource-name
$ dpckan resource create -rn nome-recurso
  • Para atualizar um recurso, execute o seguinte comando no diretório aonde o arquivo datapackage.json se encontra. Não se esqueça de modificar os últimos argumentos com o nome e id do recurso presente no arquivo datapackage.json que será atualizado
# Utilização flags --resource-name e --resource-id
$ dpckan resource update --resource-name nome-recurso --resource-id id-recurso

# Utilização alias -rn e -id para flags --resource-name e --resource-id respectivamente
$ dpckan resource update -rn nome-recurso -id id-recurso

Usando as flags

  • É possível atualizar um conjunto de dados ou recurso fora do diretório onde o arquivo datapackage.json se encontra utilizando a flag --datapackage ou -dp como abaixo:
# Utilização flag --datapackage
$ dpckan resource update --datapackage local/path/para/datapackage.json --resource-name nome-recurso --resource-id id-recurso

# Utilização alias -dp, -rn e -id para flags --datapackage,--resource-name e --resource-id respectivamente
$ dpckan resource update -dp local/path/para/datapackage.json -rn nome-recurso -id id-recurso
  • Podemos usar as flags -H para o CKAN_HOST, -k para o CKAN_KEY, -rn para o --resource_name e -id para o --resource_id, por exemplo:
# Utilização flags --ckan-host, --ckan-key, --resource-name e --resource-id
$ dpckan resource update --ckan-host $CKAN_HOST_PRODUCAO --ckan-key $CKAN_KEY_PRODUCAO --resource-name nome-recurso --resource-id id-recurso

# Utilização alias -H, -k, -rn e -id para flags --ckan-host, --ckan-key, --resource-name e --resource-id respectivamente
$ dpckan resource update -H $CKAN_HOST_PRODUCAO -k $CKAN_KEY_PRODUCAO -rn nome-recurso -id id-rescurso

Para mais exemplos, consulte a documentação

Check diff before updating a dataset

CLI

Running the diff command

dpckan dataset diff --datapackage some-path/datapackage.json 
Differences detected:
 - On field title
   - CKAN value A vowel letters dataset for tests CHANGED
   - DataPackage value A vowel letters dataset for tests
Equal fields: version, url, license_id, owner_org, tags, notes

Via Python code

Using the python diff_dataset function

import os
from dpckan.diff_dataset import diff_dataset

CKAN_HOST = os.environ.get('CKAN_HOST')
CKAN_KEY = os.environ.get('CKAN_KEY')
datapackage_path = 'local/path/para/datapackage.json'

# A chamada de funções via código Python exige passagem de todos os argumentos
diffs, oks = diff_dataset(
  ckan_host=CKAN_HOST,
  ckan_key=CKAN_KEY,
  datapackage=datapackage_path
)

diffs
[{'field_name': 'title', 'ckan_value': 'A vowel letters dataset for tests CHANGED', 'datapackage_value': 'A vowel letters dataset for tests'}]

oks
['version', 'url', 'license_id', 'owner_org', 'tags', 'notes']

Check diff for resources

CLI

Running the diff command for a resource

dpckan resource diff --datapackage some-path/datapackage.json --resource-name="This is the actual data"
Differences detected:
 - On field format
   - CKAN value: CSV
   - DataPackage value: csv
Equal fields: description

Via Python code

Using the python diff_dataset function

import os
from dpckan.diff_resource import diff_resource

CKAN_HOST = os.environ.get('CKAN_HOST')
CKAN_KEY = os.environ.get('CKAN_KEY')
datapackage_path = 'local/path/para/datapackage.json'
datapackage_path = 'dpckan/tests/data-samples/datapackage-example/datapackage.json'
resource_name = 'This is the actual data'

# A chamada de funções via código Python exige passagem de todos os argumentos
diffs, oks = diff_resource(
  ckan_host=CKAN_HOST,
  ckan_key=CKAN_KEY,
  datapackage=datapackage_path,
  resource_name=resource_name
)

diffs
[{'field_name': 'format', 'ckan_value': 'CSV', 'datapackage_value': 'csv'}]

oks
['description']

Desenvolvimento

Contribuir para o projeto

  • Prerequisitos:

    • 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 sua conta 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

  • 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.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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dpckan-0.1.6.tar.gz (12.0 MB view hashes)

Uploaded Source

Built Distribution

dpckan-0.1.6-py3-none-any.whl (23.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page