Repository: CartoDB/cartoframes
Pull request #1209 (2019-11-18 10:32:15)

Adding new naming props in Dataset and Geography
the idea is to add more user oriented naming for some fields of Dataset and Geography


Patch:
diff --git a/cartoframes/data/observatory/catalog/category.py b/cartoframes/data/observatory/catalog/category.py
index 7e8c3dd6..a1c54e0d 100644
--- a/cartoframes/data/observatory/catalog/category.py
+++ b/cartoframes/data/observatory/catalog/category.py
@@ -9,16 +9,34 @@ from .repository.geography_repo import get_geography_repo
 
 class Category(CatalogEntity):
 
+    """A CatalogDataset can be assigned to a particular categories as part of its metadata info. A Category instance
+    can be used to query datasets or geographies that belong (or are related to) that category.
+    """
+
     entity_repo = get_category_repo()
 
     @property
     def datasets(self):
+        """Get the list of datasets related to this category.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of CatalogDataset instances.
+
+        """
         return get_dataset_repo().get_all({CATEGORY_FILTER: self.id})
 
     @property
     def geographies(self):
+        """Get the list of geographies corresponding to datasets that are related to this category.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>`
+
+        """
         return get_geography_repo().get_all({CATEGORY_FILTER: self.id})
 
     @property
     def name(self):
+        """Name of this category."""
+
         return self.data['name']
diff --git a/cartoframes/data/observatory/catalog/country.py b/cartoframes/data/observatory/catalog/country.py
index 9c701bea..cace939b 100644
--- a/cartoframes/data/observatory/catalog/country.py
+++ b/cartoframes/data/observatory/catalog/country.py
@@ -9,17 +9,38 @@ from .repository.constants import COUNTRY_FILTER
 
 
 class Country(CatalogEntity):
+    """Every CatalogDataset has a country associated to it. A Country instance can be used to query datasets (or other
+    entities related to datasets) that belong to that country.
+    """
 
     entity_repo = get_country_repo()
 
     @property
     def datasets(self):
+        """Get the list of datasets covering data for this country.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of CatalogDataset instances.
+
+        """
         return get_dataset_repo().get_all({COUNTRY_FILTER: self.id})
 
     @property
     def geographies(self):
+        """Get the list of geographies covering data for this country.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Geography instances.
+
+        """
         return get_geography_repo().get_all({COUNTRY_FILTER: self.id})
 
     @property
     def categories(self):
+        """Get the list of categories that are assigned to datasets that cover data for this country.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Category instances.
+
+        """
         return get_category_repo().get_all({COUNTRY_FILTER: self.id})
diff --git a/cartoframes/data/observatory/catalog/dataset.py b/cartoframes/data/observatory/catalog/dataset.py
index cf62ac16..2f44c430 100644
--- a/cartoframes/data/observatory/catalog/dataset.py
+++ b/cartoframes/data/observatory/catalog/dataset.py
@@ -20,70 +20,129 @@ DATASET_TYPE = 'dataset'
 
 
 class CatalogDataset(CatalogEntity):
+    """A CatalogDataset represents the metadata of a particular dataset in the Data Observatory platform."""
+
     entity_repo = get_dataset_repo()
 
     @property
     def variables(self):
+        """Get the list of variables that correspond to this dataset.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Variable instances.
+
+        """
+
         return get_variable_repo().get_all({DATASET_FILTER: self.id})
 
     @property
     def variables_groups(self):
+        """Get the list of variables groups related to this dataset.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of VariableGroup instances.
+
+        """
         return get_variable_group_repo().get_all({DATASET_FILTER: self.id})
 
     @property
     def name(self):
+        """Name of this dataset."""
+
         return self.data['name']
 
     @property
     def description(self):
+        """Description of this dataset."""
+
         return self.data['description']
 
     @property
     def provider(self):
+        """Id of the Provider of this dataset."""
+
         return self.data['provider_id']
 
+    @property
+    def provider_name(self):
+        return self.data['provider_name']
+
     @property
     def category(self):
+        """Id of the Category assigned to this dataset."""
+
         return self.data['category_id']
 
+    @property
+    def category_name(self):
+        return self.data['category_name']
+
     @property
     def data_source(self):
+        """Id of the data source of this dataset."""
+
         return self.data['data_source_id']
 
     @property
     def country(self):
+        """Code (ISO 3166-1 alpha-3) of the country of this dataset."""
+
         return self.data['country_id']
 
     @property
     def language(self):
+        """Code (ISO 639-3) of the language that corresponds to the data of this dataset. """
+
         return self.data['lang']
 
     @property
     def geography(self):
+        """Id of the Geography associated to this dataset."""
+
         return self.data['geography_id']
 
+    @property
+    def geography_name(self):
+        return self.data['geography_name']
+
+    @property
+    def geography_description(self):
+        return self.data['geography_description']
+
     @property
     def temporal_aggregation(self):
+        """Time amount in which data is aggregated in this dataset."""
+
         return self.data['temporal_aggregation']
 
     @property
     def time_coverage(self):
+        """Time range that covers the data of this dataset."""
+
         return self.data['time_coverage']
 
     @property
     def update_frequency(self):
+        """Frequency in which the dataset is updated."""
+
         return self.data['update_frequency']
 
     @property
     def version(self):
+        """Version info of this dataset."""
+
         return self.data['version']
 
     @property
     def is_public_data(self):
+        """True if the content of this dataset can be accessed with public credentials. False otherwise."""
+
         return self.data['is_public_data']
 
     @property
     def summary(self):
+        """JSON object with extra metadata that summarizes different properties of the dataset content."""
+
         return self.data['summary_json']
 
     def head(self):
@@ -110,6 +169,23 @@ class CatalogDataset(CatalogEntity):
 
     @classmethod
     def get_all(cls, filters=None, credentials=None):
+        """Get all the CatalogDataset instances that comply with the indicated filters (or all of them if no filters
+        are passed. If credentials are given, only the datasets granted for those credentials are returned.
+
+        Args:
+            credentials (:py:class:`Credentials <cartoframes.auth.Credentials>`, optional):
+                credentials of CARTO user account. If provided, only datasets granted for those credentials are
+                returned.
+
+            filters (dict, optional):
+                Dict containing pairs of dataset properties and its value to be used as filters to query the available
+                datasets. If none is provided, no filters will be applied to the query.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of CatalogDataset instances.
+
+        """
+
         return cls.entity_repo.get_all(filters, credentials)
 
     def download(self, credentials=None):
diff --git a/cartoframes/data/observatory/catalog/geography.py b/cartoframes/data/observatory/catalog/geography.py
index 1a11ce91..af2e303d 100644
--- a/cartoframes/data/observatory/catalog/geography.py
+++ b/cartoframes/data/observatory/catalog/geography.py
@@ -17,50 +17,97 @@ class Geography(CatalogEntity):
 
     @property
     def datasets(self):
+        """Get the list of datasets related to this geography.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Dataset instances.
+
+        """
         return get_dataset_repo().get_all({GEOGRAPHY_FILTER: self.id})
 
     @property
     def name(self):
+        """Name of this geography."""
+
         return self.data['name']
 
     @property
     def description(self):
+        """Description of this geography."""
+
         return self.data['description']
 
     @property
     def country(self):
+        """Code (ISO 3166-1 alpha-3) of the country of this geography."""
+
         return self.data['country_id']
 
     @property
     def language(self):
+        """Code (ISO 639-3) of the language that corresponds to the data of this geography. """
+
         return self.data['lang']
 
     @property
     def provider(self):
+        """Id of the Provider of this geography."""
+
         return self.data['provider_id']
 
+    @property
+    def provider_name(self):
+        return self.data['provider_name']
+
     @property
     def geom_coverage(self):
+        """Info about the geometric coverage of this geography."""
+
         return self.data['geom_coverage']
 
     @property
     def update_frequency(self):
+        """Frequency in which the geography is updated."""
+
         return self.data['update_frequency']
 
     @property
     def version(self):
+        """Version info of this geography."""
+
         return self.data['version']
 
     @property
     def is_public_data(self):
+        """True if the content of this geography can be accessed with public credentials. False otherwise."""
+
         return self.data['is_public_data']
 
     @property
     def summary(self):
+        """JSON object with extra metadata that summarizes different properties of the dataset content."""
+
         return self.data['summary_json']
 
     @classmethod
     def get_all(cls, filters=None, credentials=None):
+        """Get all the Geography instances that comply with the indicated filters (or all of them if no filters
+        are passed. If credentials are given, only the geographies granted for those credentials are returned.
+
+        Args:
+            credentials (:py:class:`Credentials <cartoframes.auth.Credentials>`, optional):
+                credentials of CARTO user account. If provided, only datasets granted for those credentials are
+                returned.
+
+            filters (dict, optional):
+                Dict containing pairs of geography properties and its value to be used as filters to query the available
+                geographies. If none is provided, no filters will be applied to the query.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Geography instances.
+
+        """
+
         return cls.entity_repo.get_all(filters, credentials)
 
     def download(self, credentials=None):
diff --git a/cartoframes/data/observatory/catalog/provider.py b/cartoframes/data/observatory/catalog/provider.py
index 26a06b4b..daea3260 100644
--- a/cartoframes/data/observatory/catalog/provider.py
+++ b/cartoframes/data/observatory/catalog/provider.py
@@ -12,8 +12,17 @@ class Provider(CatalogEntity):
 
     @property
     def datasets(self):
+        """Get the list of datasets related to this provider.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Dataset instances.
+
+        """
+
         return get_dataset_repo().get_all({PROVIDER_FILTER: self.id})
 
     @property
     def name(self):
+        """Name of this provider."""
+
         return self.data['name']
diff --git a/cartoframes/data/observatory/catalog/repository/dataset_repo.py b/cartoframes/data/observatory/catalog/repository/dataset_repo.py
index 2ec2e2c4..59786b87 100644
--- a/cartoframes/data/observatory/catalog/repository/dataset_repo.py
+++ b/cartoframes/data/observatory/catalog/repository/dataset_repo.py
@@ -40,12 +40,16 @@ class DatasetRepository(EntityRepository):
             'slug': self._normalize_field(row, 'slug'),
             'name': self._normalize_field(row, 'name'),
             'description': self._normalize_field(row, 'description'),
-            'provider_id': self._normalize_field(row, 'provider_id'),
+            'country_id': self._normalize_field(row, 'country_id'),
+            'geography_id': self._normalize_field(row, 'geography_id'),
+            'geography_name': self._normalize_field(row, 'geography_name'),
+            'geography_description': self._normalize_field(row, 'geography_description'),
             'category_id': self._normalize_field(row, 'category_id'),
+            'category_name': self._normalize_field(row, 'category_name'),
+            'provider_id': self._normalize_field(row, 'provider_id'),
+            'provider_name': self._normalize_field(row, 'provider_name'),
             'data_source_id': self._normalize_field(row, 'data_source_id'),
-            'country_id': self._normalize_field(row, 'country_id'),
             'lang': self._normalize_field(row, 'lang'),
-            'geography_id': self._normalize_field(row, 'geography_id'),
             'temporal_aggregation': self._normalize_field(row, 'temporal_aggregation'),
             'time_coverage': self._normalize_field(row, 'time_coverage'),
             'update_frequency': self._normalize_field(row, 'update_frequency'),
diff --git a/cartoframes/data/observatory/catalog/repository/geography_repo.py b/cartoframes/data/observatory/catalog/repository/geography_repo.py
index 96326735..0793ec3f 100644
--- a/cartoframes/data/observatory/catalog/repository/geography_repo.py
+++ b/cartoframes/data/observatory/catalog/repository/geography_repo.py
@@ -48,8 +48,9 @@ class GeographyRepository(EntityRepository):
             'slug': self._normalize_field(row, 'slug'),
             'name': self._normalize_field(row, 'name'),
             'description': self._normalize_field(row, 'description'),
-            'provider_id': self._normalize_field(row, 'provider_id'),
             'country_id': self._normalize_field(row, 'country_id'),
+            'provider_id': self._normalize_field(row, 'provider_id'),
+            'provider_name': self._normalize_field(row, 'provider_name'),
             'lang': self._normalize_field(row, 'lang'),
             'geom_coverage': self._normalize_field(row, 'geom_coverage'),
             'update_frequency': self._normalize_field(row, 'update_frequency'),
diff --git a/cartoframes/data/observatory/catalog/variable.py b/cartoframes/data/observatory/catalog/variable.py
index 81798713..0f8236f1 100644
--- a/cartoframes/data/observatory/catalog/variable.py
+++ b/cartoframes/data/observatory/catalog/variable.py
@@ -16,14 +16,25 @@ class Variable(CatalogEntity):
 
     @property
     def datasets(self):
+        """Get the list of datasets related to this variable.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Dataset instances.
+
+        """
+
         return get_dataset_repo().get_all({VARIABLE_FILTER: self.id})
 
     @property
     def name(self):
+        """Name of this variable."""
+
         return self.data['name']
 
     @property
     def description(self):
+        """Description of this variable."""
+
         return self.data['description']
 
     @property
@@ -36,6 +47,8 @@ class Variable(CatalogEntity):
 
     @property
     def dataset(self):
+        """ID of the dataset to which this variable belongs."""
+
         return self.data['dataset_id']
 
     @property
@@ -44,14 +57,20 @@ class Variable(CatalogEntity):
 
     @property
     def variable_group(self):
+        """If any, ID of the variable group to which this variable belongs."""
+
         return self.data['variable_group_id']
 
     @property
     def starred(self):
+        """Boolean indicating whether this variable is a starred one or not.."""
+
         return self.data['starred']
 
     @property
     def summary(self):
+        """JSON object with extra metadata that summarizes different properties of this variable."""
+
         return self.data['summary_json']
 
     @property
diff --git a/cartoframes/data/observatory/catalog/variable_group.py b/cartoframes/data/observatory/catalog/variable_group.py
index 6bf7c7a9..e8d7138e 100644
--- a/cartoframes/data/observatory/catalog/variable_group.py
+++ b/cartoframes/data/observatory/catalog/variable_group.py
@@ -12,16 +12,29 @@ class VariableGroup(CatalogEntity):
 
     @property
     def variables(self):
+        """Get the list of variables included in this variable group.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>` List of Variable instances.
+
+        """
+
         return get_variable_repo().get_all({VARIABLE_GROUP_FILTER: self.id})
 
     @property
     def name(self):
+        """Name of this variable group."""
+
         return self.data['name']
 
     @property
     def dataset(self):
+        """ID of the dataset related to this variable group."""
+
         return self.data['dataset_id']
 
     @property
     def starred(self):
+        """Boolean indicating whether this variable group is a starred one or not.."""
+
         return self.data['starred']


Test patch:
diff --git a/tests/unit/data/observatory/catalog/examples.py b/tests/unit/data/observatory/catalog/examples.py
index c8dcef16..7a919e45 100644
--- a/tests/unit/data/observatory/catalog/examples.py
+++ b/tests/unit/data/observatory/catalog/examples.py
@@ -31,6 +31,7 @@ db_geography1 = {
     'name': 'ESP - Census',
     'description': 'Geography data for Spanish census',
     'provider_id': 'bbva',
+    'provider_name': 'bbva',
     'country_id': 'esp',
     'lang': 'esp',
     'geom_coverage': '',
@@ -45,6 +46,7 @@ db_geography2 = {
     'name': 'ESP - Municipalities',
     'description': 'Geography data for Spanish municipalities',
     'provider_id': 'bbva',
+    'provider_name': 'bbva',
     'country_id': 'esp',
     'lang': 'esp',
     'geom_coverage': '',
@@ -63,11 +65,15 @@ db_dataset1 = {
     'name': 'Basic Stats - Census',
     'description': 'Basic stats on 2019 Spanish census',
     'provider_id': 'bbva',
+    'provider_name': 'bbva',
     'category_id': 'demographics',
+    'category_name': 'demographics',
     'data_source_id': 'basicstats',
     'country_id': 'esp',
     'lang': 'esp',
     'geography_id': 'carto-do-public-data.tiger.geography_esp_census_2019',
+    'geography_name': 'Tiger municipalities from Spain',
+    'geography_description': 'Points',
     'temporal_aggregation': '5yrs',
     'time_coverage': ['2006-01-01', '2010-01-01'],
     'update_frequency': 'monthly',
@@ -81,11 +87,15 @@ db_dataset2 = {
     'name': 'Basic Stats - Municipalities',
     'description': 'Basic stats on 2019 Spanish municipalities',
     'provider_id': 'bbva',
+    'provider_name': 'bbva',
     'category_id': 'demographics',
+    'category_name': 'demographics',
     'data_source_id': 'basicstats',
     'country_id': 'esp',
     'lang': 'esp',
     'geography_id': 'carto-do-public-data.tiger.geography_esp_municipalities_2019',
+    'geography_name': 'Tiger municipalities from Spain',
+    'geography_description': 'Points',
     'temporal_aggregation': '5yrs',
     'time_coverage': ['2006-01-01', '2010-01-01'],
     'update_frequency': 'monthly',
diff --git a/tests/unit/data/observatory/catalog/repository/test_dataset_repo.py b/tests/unit/data/observatory/catalog/repository/test_dataset_repo.py
index 8aa20555..fac536b9 100644
--- a/tests/unit/data/observatory/catalog/repository/test_dataset_repo.py
+++ b/tests/unit/data/observatory/catalog/repository/test_dataset_repo.py
@@ -97,7 +97,6 @@ class TestDatasetRepo(object):
         repo = DatasetRepository()
 
         # When
-        print(requested_id)
         dataset = repo.get_by_id(requested_id)
 
         # Then
@@ -183,11 +182,15 @@ class TestDatasetRepo(object):
             'name': None,
             'description': None,
             'provider_id': None,
+            'provider_name': None,
             'category_id': None,
+            'category_name': None,
             'data_source_id': None,
             'country_id': None,
             'lang': None,
             'geography_id': None,
+            'geography_name': None,
+            'geography_description': None,
             'temporal_aggregation': None,
             'time_coverage': None,
             'update_frequency': None,
diff --git a/tests/unit/data/observatory/catalog/repository/test_geography_repo.py b/tests/unit/data/observatory/catalog/repository/test_geography_repo.py
index 2009d2a2..5c6172da 100644
--- a/tests/unit/data/observatory/catalog/repository/test_geography_repo.py
+++ b/tests/unit/data/observatory/catalog/repository/test_geography_repo.py
@@ -194,6 +194,7 @@ class TestGeographyRepo(object):
             'name': None,
             'description': None,
             'provider_id': None,
+            'provider_name': None,
             'country_id': None,
             'lang': None,
             'geom_coverage': None,