Merge branch 'master' of https://github.com/datosgobar/pydatajson

* 'master' of https://github.com/datosgobar/pydatajson:
  test para los wrappers de push_dataset
  documentacion para push_new_themes y 3 wrappers
  Cambio el return de push_themes y agrego tests para esa función
  Hago owner_org opcional para harvest_catalog y agrego docstrings
  Devuelvo los ids de los datasets federados y restaurados
  wrappers para restaurar y federar a nivel catalogo

# Conflicts:
#	docs/MANUAL.md
#	pydatajson/federation.py

docs/MANUAL.md

@@ -332,7 +332,7 @@ Existen dos métodos, cuyos reportes se incluyen diariamente entre los archivos
 ### Métodos para federación de datasets
 
 - **pydatajson.DataJson.push_dataset_to_ckan()**: Copia la metadata de un dataset y la escribe en un portal de CKAN.
-Toma los siguientes parámetros: 
+Toma los siguientes parámetros:
   - **owner_org**: La organización a la que pertence el dataset. Debe encontrarse en el portal de destino.
   - **dataset_origin_identifier**: Identificador del dataset en el catálogo de origen.
   - **portal_url**: URL del portal de CKAN de destino.
@@ -345,7 +345,7 @@ Toma los siguientes parámetros:
   - **demote_themes** (opcional, default: True): Si está en true, los labels de los themes del dataset, se escriben como
   tags de CKAN; sino,se pasan como grupo.
 
-  
+
   Retorna el id en el nodo de destino del dataset federado.
 
   **Advertencia**: La función `push_dataset_to_ckan()` sólo garantiza consistencia con los estándares de CKAN. Para
@@ -368,14 +368,60 @@ Toma los siguientes parámetros:
 
 - **pydatajson.DataJson.push_theme_to_ckan()**: Crea un tema en el portal de destino
 Toma los siguientes parámetros:
-    - **portal_url**: La URL del portal CKAN. Debe implementar la funcionalidad de `/data.json`.
-    - **apikey**: La apikey de un usuario con los permisos que le permitan borrar el dataset.
+    - **portal_url**: La URL del portal CKAN.
+    - **apikey**: La apikey de un usuario con los permisos que le permitan crear un grupo.
     - **identifier** (opcional, default: None): Id del `theme` que se quiere federar, en el catálogo de origen.
     - **label** (opcional, default: None): label del `theme` que se quiere federar, en el catálogo de origen.
 
     Debe pasarse por lo menos uno de los 2 parámetros opcionales. En caso de que se provean los 2, se prioriza el
     identifier sobre el label.
 
+- **pydatajson.DataJson.push_new_themes()**: Toma los temas de la taxonomía de un DataJson y los crea en el catálogo de
+    destino si no existen.
+Toma los siguientes parámetros:
+    - **portal_url**: La URL del portal CKAN adonde se escribiran los temas.
+    - **apikey**: La apikey de un usuario con los permisos que le permitan crear los grupos.
+
+
+Hay también funciones que facilitan el uso de `push_dataset_to_ckan()`:
+
+- **pydatajson.DataJson.harvest_dataset_to_ckan()**: Federa la metadata de un dataset en un portal de CKAN.
+Toma los siguientes parámetros:
+  - **owner_org**: La organización a la que pertence el dataset. Debe encontrarse en el portal de destino.
+  - **dataset_origin_identifier**: Identificador del dataset en el catálogo de origen.
+  - **portal_url**: URL del portal de CKAN de destino.
+  - **apikey**: La apikey de un usuario del portal de destino con los permisos para crear el dataset bajo la
+  organización pasada como parámetro.
+  - **catalog_id**: El prefijo que va a preceder el id y name del dataset en el portal
+  destino, separado por un guión.
+
+
+  Retorna el id en el nodo de destino del dataset federado.
+
+- **pydatajson.DataJson.restore_dataset_to_ckan()**: Restaura la metadata de un dataset en un portal de CKAN.
+Toma los siguientes parámetros:
+  - **owner_org**: La organización a la que pertence el dataset. Debe encontrarse en el portal de destino.
+  - **dataset_origin_identifier**: Identificador del dataset en el catálogo de origen.
+  - **portal_url**: URL del portal de CKAN de destino.
+  - **apikey**: La apikey de un usuario del portal de destino con los permisos para crear el dataset bajo la
+  organización pasada como parámetro.
+
+
+  Retorna el id del dataset restaurado.
+
+- **pydatajson.DataJson.harvest_catalog_to_ckan()**: Federa los datasets de un catálogo al portal pasado por parámetro.
+Toma los siguientes parámetros:
+  - **dataset_origin_identifier**: Identificador del dataset en el catálogo de origen.
+  - **portal_url**: URL del portal de CKAN de destino.
+  - **apikey**: La apikey de un usuario del portal de destino con los permisos para crear el dataset.
+  - **catalog_id**: El prefijo que va a preceder el id y name del dataset en el portal
+  destino, separado por un guión.
+  - **dataset_list** (opcional, default: None): Lista de ids de los datasets a federar. Si no se pasa, se federan todos
+  los datasets del catálogo.
+  - **owner_org** (opcional, default: None): La organización a la que pertence el dataset. Debe encontrarse en el
+  portal de destino. Si no se pasa, se toma como organización el catalog_id
+
+  Retorna el id en el nodo de destino de los datasets federados.
 
 ## Anexo I: Estructura de respuestas
 

pydatajson/federation.py

@@ -147,13 +147,122 @@ def push_theme_to_ckan(catalog, portal_url, apikey,
 
 def restore_dataset_to_ckan(catalog, owner_org, dataset_origin_identifier,
                             portal_url, apikey):
+    """Restaura la metadata de un dataset en el portal pasado por parámetro.
 
+        Args:
+            catalog (DataJson): El catálogo de origen que contiene el dataset.
+            owner_org (str): La organización a la cual pertence el dataset.
+            dataset_origin_identifier (str): El id del dataset que se va a
+                restaurar.
+            portal_url (str): La URL del portal CKAN de destino.
+            apikey (str): La apikey de un usuario con los permisos que le
+                permitan crear o actualizar el dataset.
+        Returns:
+            str: El id del dataset restaurado.
+    """
     return push_dataset_to_ckan(catalog, owner_org, dataset_origin_identifier,
                                 portal_url, apikey, None, False, False)
 
 
 def harvest_dataset_to_ckan(catalog, owner_org, dataset_origin_identifier,
                             portal_url, apikey, catalog_id):
+    """Federa la metadata de un dataset en el portal pasado por parámetro.
+
+        Args:
+            catalog (DataJson): El catálogo de origen que contiene el dataset.
+            owner_org (str): La organización a la cual pertence el dataset.
+            dataset_origin_identifier (str): El id del dataset que se va a
+                restaurar.
+            portal_url (str): La URL del portal CKAN de destino.
+            apikey (str): La apikey de un usuario con los permisos que le
+                permitan crear o actualizar el dataset.
+            catalog_id(str): El id que prep
+        Returns:
+            str: El id del dataset restaurado.
+    """
 
     return push_dataset_to_ckan(catalog, owner_org, dataset_origin_identifier,
                                 portal_url, apikey, catalog_id=catalog_id)
+
+
+def restore_catalog_to_ckan(catalog, owner_org, portal_url, apikey,
+                            dataset_list=None):
+    """Restaura los datasets de un catálogo al portal pasado por parámetro.
+        Si hay temas presentes en el DataJson que no están en el portal de
+        CKAN, los genera.
+
+        Args:
+            catalog (DataJson): El catálogo de origen que se restaura.
+            portal_url (str): La URL del portal CKAN de destino.
+            apikey (str): La apikey de un usuario con los permisos que le
+                permitan crear o actualizar el dataset.
+            dataset_list(list(str)): Los ids de los datasets a restaurar. Si no
+                se pasa una lista, todos los datasests se restauran.
+            owner_org (str): La organización a la cual pertencen los datasets.
+                Si no se pasa, se utiliza el catalog_id.
+        Returns:
+            str: El id del dataset en el catálogo de destino.
+    """
+    push_new_themes(catalog, portal_url, apikey)
+    dataset_list = dataset_list or [ds['identifier']
+                                    for ds in catalog.datasets]
+    restored = []
+    for dataset_id in dataset_list:
+        restored_id = restore_dataset_to_ckan(
+            catalog, owner_org, dataset_id, portal_url, apikey)
+        restored.append(restored_id)
+    return restored
+
+
+def harvest_catalog_to_ckan(catalog, portal_url, apikey, catalog_id,
+                            dataset_list=None, owner_org=None):
+    """Federa los datasets de un catálogo al portal pasado por parámetro.
+
+        Args:
+            catalog (DataJson): El catálogo de origen que se federa.
+            portal_url (str): La URL del portal CKAN de destino.
+            apikey (str): La apikey de un usuario con los permisos que le
+                permitan crear o actualizar el dataset.
+            catalog_id (str): El prefijo con el que va a preceder el id del
+                dataset en catálogo destino.
+            dataset_list(list(str)): Los ids de los datasets a federar. Si no
+                se pasa una lista, todos los datasests se federan.
+            owner_org (str): La organización a la cual pertencen los datasets.
+                Si no se pasa, se utiliza el catalog_id.
+        Returns:
+            str: El id del dataset en el catálogo de destino.
+    """
+    dataset_list = dataset_list or [ds['identifier']
+                                    for ds in catalog.datasets]
+    owner_org = owner_org or catalog_id
+    harvested = []
+    for dataset_id in dataset_list:
+        harvested_id = harvest_dataset_to_ckan(
+            catalog, owner_org, dataset_id, portal_url, apikey, catalog_id)
+        harvested.append(harvested_id)
+    return harvested
+
+
+def push_new_themes(catalog, portal_url, apikey):
+    """Toma un catálogo y escribe los temas de la taxonomía que no están
+    presentes.
+
+        Args:
+            catalog (DataJson): El catálogo de origen que contiene la
+                taxonomía.
+            portal_url (str): La URL del portal CKAN de destino.
+            apikey (str): La apikey de un usuario con los permisos que le
+                permitan crear o actualizar el dataset.
+        Returns:
+            str: Los ids de los temas creados.
+    """
+    ckan_portal = RemoteCKAN(portal_url, apikey=apikey)
+    existing_themes = ckan_portal.call_action('group_list')
+    new_themes = [theme['id'] for theme in catalog[
+        'themeTaxonomy'] if theme['id'] not in existing_themes]
+    pushed_names = []
+    for new_theme in new_themes:
+        name = push_theme_to_ckan(
+            catalog, portal_url, apikey, identifier=new_theme)
+        pushed_names.append(name)
+    return pushed_names