Paquete en python con herramientas para generar y validar metadatos de catálogos de datos en formato data.json.
Project description
pydatajson
==========
[![Coverage Status](https://coveralls.io/repos/github/datosgobar/pydatajson/badge.svg?branch=master)](https://coveralls.io/github/datosgobar/pydatajson?branch=master)
[![Build Status](https://travis-ci.org/datosgobar/pydatajson.svg?branch=master)](https://travis-ci.org/datosgobar/pydatajson)
[![PyPI](https://badge.fury.io/py/pydatajson.svg)](http://badge.fury.io/py/pydatajson)
[![Stories in Ready](https://badge.waffle.io/datosgobar/pydatajson.png?label=ready&title=Ready)](https://waffle.io/datosgobar/pydatajson)
[![Documentation Status](http://readthedocs.org/projects/pydatajson/badge/?version=latest)](http://pydatajson.readthedocs.io/en/latest/?badge=latest)
Paquete en python con herramientas para manipular y validar metadatos de catálogos de datos en formato data.json.
* Licencia: MIT license
* Documentación: [https://pydatajson.readthedocs.io](https://pydatajson.readthedocs.io)
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Indice
- [Instalación](#instalaci%C3%B3n)
- [Uso](#uso)
- [Setup](#setup)
- [Posibles validaciones de catálogos](#posibles-validaciones-de-cat%C3%A1logos)
- [Ubicación del catálogo a validar](#ubicaci%C3%B3n-del-cat%C3%A1logo-a-validar)
- [Ejemplos](#ejemplos)
- [Archivo data.json local](#archivo-datajson-local)
- [Archivo data.json remoto](#archivo-datajson-remoto)
- [Diccionario (data.json deserializado)](#diccionario-datajson-deserializado)
- [Tests](#tests)
- [Créditos](#cr%C3%A9ditos)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Instalación
* **Producción:** Desde cualquier parte
```bash
$ pip install pydatajson
```
* **Desarrollo:** Clonar este repositorio, y desde su raíz, ejecutar:
```bash
$ pip install -e .
```
## Uso
La librería implementa el objeto `DataJson` con varios métodos para verificar la integridad de archivos de metadatos `data.json` (locales o remotos) y manipular su contenido.
### Setup
`DataJson` utiliza un esquema default que cumple con el perfil de metadatos recomendado en la [Guía para el uso y la publicación de metadatos (v0.1)](https://github.com/datosgobar/paquete-apertura-datos/raw/master/docs/Gu%C3%ADa%20para%20el%20uso%20y%20la%20publicaci%C3%B3n%20de%20metadatos%20(v0.1).pdf) del [Paquete de Apertura de Datos](https://github.com/datosgobar/paquete-apertura-datos).
```python
from pydatajson import DataJson
dj = DataJson()
```
Si se desea utilizar un esquema alternativo, se debe especificar un **directorio absoluto** donde se almacenan los esquemas (`schema_dir`) y un nombre de esquema de validación (`schema_filename`), relativo al directorio de los esquemas. Por ejemplo, si nuestro esquema alternativo se encuentra en `/home/datosgobar/metadatos-portal/esquema_de_validacion.json`, especificaremos:
```python
from pydatajson import DataJson
dj = DataJson(schema_filename="esquema_de_validacion.json",
schema_dir="/home/datosgobar/metadatos-portal")
```
### Posibles validaciones de catálogos
- Si se desea un **resultado sencillo (V o F)** sobre la validez de la estructura del catálogo, se utilizará **`is_valid_catalog(datajson_path_or_url)`**.
- Si se desea un **mensaje de error detallado**, se utilizará **`validate_catalog(datajson_path_or_url)`**.
### Ubicación del catálogo a validar
Ambos métodos mencionados de `DataJson()` son capaces de validar archivos `data.json` locales o remotos:
- Para validar un **archivo local**, `datajson_path_or_url` deberá ser el **path absoluto** a él.
- Para validar un **archivo remoto**, `datajson_path_or_url` deberá ser una **URL que comience con 'http' o 'https'**.
Alternativamente, también se pueden validar **diccionarios**, es decir, el resultado de deserializar un archivo `data.json` en una variable.
Por conveniencia, la carpeta [`tests/samples/`](tests/samples/) contiene varios ejemplos de `data.json`s bien y mal formados con distintos tipos de errores.
### Ejemplos de validación de catálogos
#### Archivo data.json local
```python
from pydatajson import DataJson
dj = DataJson()
datajson_path = "tests/samples/full_data.json"
validation_result = dj.is_valid_catalog(datajson_path)
validation_report = dj.validate_catalog(datajson_path)
print validation_result
True
print validation_report
{
"status": "OK",
"error": {
"catalog": {
"status": "OK",
"errors": [],
"title": "Datos Argentina"
},
"dataset": [
{
"status": "OK",
"errors": [],
"title": "Sistema de contrataciones electrónicas"
}
]
}
}
```
#### Archivo data.json remoto
```python
datajson_url = "http://181.209.63.71/data.json"
validation_result = dj.is_valid_catalog(datajson_url)
validation_report = dj.validate_catalog(datajson_url)
print validation_result
False
print validation_report
{
"status": "ERROR",
"error": {
"catalog": {
"status": "ERROR",
"errors": [
{
"instance": "",
"validator": "format",
"path": [
"publisher",
"mbox"
],
"message": "u'' is not a u'email'",
"error_code": 2,
"validator_value": "email"
},
{
"instance": "",
"validator": "minLength",
"path": [
"publisher",
"name"
],
"message": "u'' is too short",
"error_code": 2,
"validator_value": 1
}
],
"title": "Andino"
},
"dataset": [
{
"status": "OK",
"errors": [],
"title": "Dataset Demo"
}
]
}
}
```
#### Diccionario (data.json deserializado)
El siguiente fragmento de código tendrá resultados idénticos al primero:
```python
import json
datajson_path = "tests/samples/full_data.json"
datajson = json.load(datajson_path)
validation_result = dj.is_valid_catalog(datajson)
validation_report = dj.validate_catalog(datajson)
(...)
```
### Ejemplos de generación de reportes y configuraciones del Harvester
Si ya se sabe que se desean cosechar todos los datasets [válidos] de uno o varios catálogos, se pueden utilizar directamente el método `generate_harvester_config()`, proveyendo `harvest='all'` o `harvest='valid'` respectivamente. Si se desea revisar manualmente la lista de datasets contenidos, se puede invocar primero `generate_datasets_report()`, editar el reporte generado y luego proveérselo a `generate_harvester_config()`, junto con la opción `harvest='report'`.
#### Crear un archivo de configuración eligiendo manualmente los datasets a federar
```python
catalogs = ["tests/samples/full_data.json", "http://181.209.63.71/data.json"]
report_path = "path/to/report.xlsx"
dj.generate_datasets_report(
catalogs=catalogs,
harvest='none', # El reporte tendrá `harvest==0` para todos los datasets
export_path=report_path
)
# A continuación, se debe editar el archivo de Excel 'path/to/report.xlsx',
# cambiando a '1' el campo 'harvest' en los datasets que se quieran cosechar.
config_path = 'path/to/config.csv'
dj.generate_harvester_config(
harvest='report',
report=report_path,
export_path=config_path
)
```
El archivo `config_path` puede ser provisto a Harvester para federar los datasets elegidos al editar el reporte intermedio `report_path`.
#### Crear un archivo de configuración que incluya únicamente los datasets con metadata válida
Conservando las variables anteriores:
```python
dj.generate_harvester_config(
catalogs=catalogs,
harvest='valid'
export_path='path/to/config.csv'
)
```
## Tests
Los tests se corren con `nose`. Desde la raíz del repositorio:
**Configuración inicial:**
```bash
$ pip install nose
$ mkdir tests/temp
```
**Correr la suite de tests:**
```bash
$ nosetests
```
## Créditos
El validador de archivos `data.json` desarrollado es mayormente un envoltorio (*wrapper*) alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el vocabulario definido por [JSONSchema.org](http://json-schema.org/) para anotar y validar archivos JSON.
History
=======
0.1.7 (2017-01-10)
------------------
* Se agrega el módulo `xlsx_to_json`, con dos métodos para lectura de archivos locales o remotos, sean JSON genéricos (`xlsx_to_json.read_json()`) o metadatos de catálogos en formato XLSX (`read_local_xlsx_catalog()`).
* Se agrega el método `pydatajson.read_catalog()` que interpreta todos las representaciones externas o internas de catálogos conocidas, y devuelve un diccionario con sus metadatos.
0.1.6 (2017-01-04)
------------------
* Se incorpora el método `DataJson.generate_harvestable_catalogs()`, que filtra los datasets no deseados de un conjunto de catálogos.
* Se agrega el parámetro `harvest` a los métodos `DataJson.generate_harvestable_catalogs()`, `DataJson.generate_datasets_report()` y `DataJson.generate_harvester_config()`, para controlar el criterio de elección de los datasets a cosechar.
* Se agrega el parámetro `export_path` a los métodos `DataJson.generate_harvestable_catalogs()`, `DataJson.generate_datasets_report()` y `DataJson.generate_harvester_config()`, para controlar la exportación de sus resultados.
0.1.4 (2016-12-23)
------------------
* Se incorpora el método `DataJson.generate_datasets_report()`, que reporta sobre los datasets y la calidad de calidad de metadatos de un conjunto de catálogos.
* Se incorpora el método `DataJson.generate_harvester_config()`, que crea archivos de configuración para el Harvester a partir de los reportes de `generate_datasets_report()`.
0.1.3 (2016-12-19)
------------------
* Al resultado de `DataJson.validate_catalog()` se le incorpora una lista (`"errors"`) con información de los errores encontrados durante la validación en cada nivel de jerarquía ("catalog" y cada elemento de "dataset")
0.1.2 (2016-12-14)
------------------
* Se incorpora validación de tipo y formato de campo
* Los métodos `DataJson.is_valid_catalog()` y `DataJson.validate_catalog()` ahora aceptan un `dict` además de un `path/to/data.json` o una url a un data.json.
0.1.0 (2016-12-01)
------------------
Primera versión para uso productivo del paquete.
* La instalación via `pip install` debería reconocer correctamente la ubicación de los validadores por default.
* El manejo de data.json's ubicados remotamente se hace en función del resultado de `urlparse.urlparse`
* El formato de respuesta de `validate_catalog` se adecúa a la última especificación (ver [`samples/validate_catalog_returns.json`](samples/validate_catalog_returns.json).
0.0.13 (2016-11-25)
-------------------
* Intentar que la instalación del paquete sepa donde están instalados los schemas por default
0.0.12 (2016-11-25)
-------------------
* Primera versión propuesta para v0.1.0
==========
[![Coverage Status](https://coveralls.io/repos/github/datosgobar/pydatajson/badge.svg?branch=master)](https://coveralls.io/github/datosgobar/pydatajson?branch=master)
[![Build Status](https://travis-ci.org/datosgobar/pydatajson.svg?branch=master)](https://travis-ci.org/datosgobar/pydatajson)
[![PyPI](https://badge.fury.io/py/pydatajson.svg)](http://badge.fury.io/py/pydatajson)
[![Stories in Ready](https://badge.waffle.io/datosgobar/pydatajson.png?label=ready&title=Ready)](https://waffle.io/datosgobar/pydatajson)
[![Documentation Status](http://readthedocs.org/projects/pydatajson/badge/?version=latest)](http://pydatajson.readthedocs.io/en/latest/?badge=latest)
Paquete en python con herramientas para manipular y validar metadatos de catálogos de datos en formato data.json.
* Licencia: MIT license
* Documentación: [https://pydatajson.readthedocs.io](https://pydatajson.readthedocs.io)
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Indice
- [Instalación](#instalaci%C3%B3n)
- [Uso](#uso)
- [Setup](#setup)
- [Posibles validaciones de catálogos](#posibles-validaciones-de-cat%C3%A1logos)
- [Ubicación del catálogo a validar](#ubicaci%C3%B3n-del-cat%C3%A1logo-a-validar)
- [Ejemplos](#ejemplos)
- [Archivo data.json local](#archivo-datajson-local)
- [Archivo data.json remoto](#archivo-datajson-remoto)
- [Diccionario (data.json deserializado)](#diccionario-datajson-deserializado)
- [Tests](#tests)
- [Créditos](#cr%C3%A9ditos)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Instalación
* **Producción:** Desde cualquier parte
```bash
$ pip install pydatajson
```
* **Desarrollo:** Clonar este repositorio, y desde su raíz, ejecutar:
```bash
$ pip install -e .
```
## Uso
La librería implementa el objeto `DataJson` con varios métodos para verificar la integridad de archivos de metadatos `data.json` (locales o remotos) y manipular su contenido.
### Setup
`DataJson` utiliza un esquema default que cumple con el perfil de metadatos recomendado en la [Guía para el uso y la publicación de metadatos (v0.1)](https://github.com/datosgobar/paquete-apertura-datos/raw/master/docs/Gu%C3%ADa%20para%20el%20uso%20y%20la%20publicaci%C3%B3n%20de%20metadatos%20(v0.1).pdf) del [Paquete de Apertura de Datos](https://github.com/datosgobar/paquete-apertura-datos).
```python
from pydatajson import DataJson
dj = DataJson()
```
Si se desea utilizar un esquema alternativo, se debe especificar un **directorio absoluto** donde se almacenan los esquemas (`schema_dir`) y un nombre de esquema de validación (`schema_filename`), relativo al directorio de los esquemas. Por ejemplo, si nuestro esquema alternativo se encuentra en `/home/datosgobar/metadatos-portal/esquema_de_validacion.json`, especificaremos:
```python
from pydatajson import DataJson
dj = DataJson(schema_filename="esquema_de_validacion.json",
schema_dir="/home/datosgobar/metadatos-portal")
```
### Posibles validaciones de catálogos
- Si se desea un **resultado sencillo (V o F)** sobre la validez de la estructura del catálogo, se utilizará **`is_valid_catalog(datajson_path_or_url)`**.
- Si se desea un **mensaje de error detallado**, se utilizará **`validate_catalog(datajson_path_or_url)`**.
### Ubicación del catálogo a validar
Ambos métodos mencionados de `DataJson()` son capaces de validar archivos `data.json` locales o remotos:
- Para validar un **archivo local**, `datajson_path_or_url` deberá ser el **path absoluto** a él.
- Para validar un **archivo remoto**, `datajson_path_or_url` deberá ser una **URL que comience con 'http' o 'https'**.
Alternativamente, también se pueden validar **diccionarios**, es decir, el resultado de deserializar un archivo `data.json` en una variable.
Por conveniencia, la carpeta [`tests/samples/`](tests/samples/) contiene varios ejemplos de `data.json`s bien y mal formados con distintos tipos de errores.
### Ejemplos de validación de catálogos
#### Archivo data.json local
```python
from pydatajson import DataJson
dj = DataJson()
datajson_path = "tests/samples/full_data.json"
validation_result = dj.is_valid_catalog(datajson_path)
validation_report = dj.validate_catalog(datajson_path)
print validation_result
True
print validation_report
{
"status": "OK",
"error": {
"catalog": {
"status": "OK",
"errors": [],
"title": "Datos Argentina"
},
"dataset": [
{
"status": "OK",
"errors": [],
"title": "Sistema de contrataciones electrónicas"
}
]
}
}
```
#### Archivo data.json remoto
```python
datajson_url = "http://181.209.63.71/data.json"
validation_result = dj.is_valid_catalog(datajson_url)
validation_report = dj.validate_catalog(datajson_url)
print validation_result
False
print validation_report
{
"status": "ERROR",
"error": {
"catalog": {
"status": "ERROR",
"errors": [
{
"instance": "",
"validator": "format",
"path": [
"publisher",
"mbox"
],
"message": "u'' is not a u'email'",
"error_code": 2,
"validator_value": "email"
},
{
"instance": "",
"validator": "minLength",
"path": [
"publisher",
"name"
],
"message": "u'' is too short",
"error_code": 2,
"validator_value": 1
}
],
"title": "Andino"
},
"dataset": [
{
"status": "OK",
"errors": [],
"title": "Dataset Demo"
}
]
}
}
```
#### Diccionario (data.json deserializado)
El siguiente fragmento de código tendrá resultados idénticos al primero:
```python
import json
datajson_path = "tests/samples/full_data.json"
datajson = json.load(datajson_path)
validation_result = dj.is_valid_catalog(datajson)
validation_report = dj.validate_catalog(datajson)
(...)
```
### Ejemplos de generación de reportes y configuraciones del Harvester
Si ya se sabe que se desean cosechar todos los datasets [válidos] de uno o varios catálogos, se pueden utilizar directamente el método `generate_harvester_config()`, proveyendo `harvest='all'` o `harvest='valid'` respectivamente. Si se desea revisar manualmente la lista de datasets contenidos, se puede invocar primero `generate_datasets_report()`, editar el reporte generado y luego proveérselo a `generate_harvester_config()`, junto con la opción `harvest='report'`.
#### Crear un archivo de configuración eligiendo manualmente los datasets a federar
```python
catalogs = ["tests/samples/full_data.json", "http://181.209.63.71/data.json"]
report_path = "path/to/report.xlsx"
dj.generate_datasets_report(
catalogs=catalogs,
harvest='none', # El reporte tendrá `harvest==0` para todos los datasets
export_path=report_path
)
# A continuación, se debe editar el archivo de Excel 'path/to/report.xlsx',
# cambiando a '1' el campo 'harvest' en los datasets que se quieran cosechar.
config_path = 'path/to/config.csv'
dj.generate_harvester_config(
harvest='report',
report=report_path,
export_path=config_path
)
```
El archivo `config_path` puede ser provisto a Harvester para federar los datasets elegidos al editar el reporte intermedio `report_path`.
#### Crear un archivo de configuración que incluya únicamente los datasets con metadata válida
Conservando las variables anteriores:
```python
dj.generate_harvester_config(
catalogs=catalogs,
harvest='valid'
export_path='path/to/config.csv'
)
```
## Tests
Los tests se corren con `nose`. Desde la raíz del repositorio:
**Configuración inicial:**
```bash
$ pip install nose
$ mkdir tests/temp
```
**Correr la suite de tests:**
```bash
$ nosetests
```
## Créditos
El validador de archivos `data.json` desarrollado es mayormente un envoltorio (*wrapper*) alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el vocabulario definido por [JSONSchema.org](http://json-schema.org/) para anotar y validar archivos JSON.
History
=======
0.1.7 (2017-01-10)
------------------
* Se agrega el módulo `xlsx_to_json`, con dos métodos para lectura de archivos locales o remotos, sean JSON genéricos (`xlsx_to_json.read_json()`) o metadatos de catálogos en formato XLSX (`read_local_xlsx_catalog()`).
* Se agrega el método `pydatajson.read_catalog()` que interpreta todos las representaciones externas o internas de catálogos conocidas, y devuelve un diccionario con sus metadatos.
0.1.6 (2017-01-04)
------------------
* Se incorpora el método `DataJson.generate_harvestable_catalogs()`, que filtra los datasets no deseados de un conjunto de catálogos.
* Se agrega el parámetro `harvest` a los métodos `DataJson.generate_harvestable_catalogs()`, `DataJson.generate_datasets_report()` y `DataJson.generate_harvester_config()`, para controlar el criterio de elección de los datasets a cosechar.
* Se agrega el parámetro `export_path` a los métodos `DataJson.generate_harvestable_catalogs()`, `DataJson.generate_datasets_report()` y `DataJson.generate_harvester_config()`, para controlar la exportación de sus resultados.
0.1.4 (2016-12-23)
------------------
* Se incorpora el método `DataJson.generate_datasets_report()`, que reporta sobre los datasets y la calidad de calidad de metadatos de un conjunto de catálogos.
* Se incorpora el método `DataJson.generate_harvester_config()`, que crea archivos de configuración para el Harvester a partir de los reportes de `generate_datasets_report()`.
0.1.3 (2016-12-19)
------------------
* Al resultado de `DataJson.validate_catalog()` se le incorpora una lista (`"errors"`) con información de los errores encontrados durante la validación en cada nivel de jerarquía ("catalog" y cada elemento de "dataset")
0.1.2 (2016-12-14)
------------------
* Se incorpora validación de tipo y formato de campo
* Los métodos `DataJson.is_valid_catalog()` y `DataJson.validate_catalog()` ahora aceptan un `dict` además de un `path/to/data.json` o una url a un data.json.
0.1.0 (2016-12-01)
------------------
Primera versión para uso productivo del paquete.
* La instalación via `pip install` debería reconocer correctamente la ubicación de los validadores por default.
* El manejo de data.json's ubicados remotamente se hace en función del resultado de `urlparse.urlparse`
* El formato de respuesta de `validate_catalog` se adecúa a la última especificación (ver [`samples/validate_catalog_returns.json`](samples/validate_catalog_returns.json).
0.0.13 (2016-11-25)
-------------------
* Intentar que la instalación del paquete sepa donde están instalados los schemas por default
0.0.12 (2016-11-25)
-------------------
* Primera versión propuesta para v0.1.0
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pydatajson-0.1.11.tar.gz
(122.5 kB
view hashes)
Built Distribution
Close
Hashes for pydatajson-0.1.11-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 440fc17afc45fc23bc724fed07bfdc31d2a95da55d03df1851dcc9f866d4ca64 |
|
MD5 | 974304f7a9dd7460632644a21982dfd0 |
|
BLAKE2b-256 | 8974ca08b9b8ce278703b1592533719573458226f3c2842dea14d3104a503a92 |