Merge pull request #1209 from CartoDB/adding-naming-props

Adding new naming props in Dataset and Geography

cartoframes/data/observatory/catalog/category.py

@@ -9,16 +9,34 @@
 
 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']

cartoframes/data/observatory/catalog/country.py

@@ -9,17 +9,38 @@
 
 
 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})

cartoframes/data/observatory/catalog/dataset.py

@@ -20,70 +20,129 @@
 
 
 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 @@ def describe(self):
 
     @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):

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):

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']

cartoframes/data/observatory/catalog/repository/dataset_repo.py

@@ -40,12 +40,16 @@ def _map_row(self, row):
             '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'),

cartoframes/data/observatory/catalog/repository/geography_repo.py

@@ -48,8 +48,9 @@ def _map_row(self, row):
             '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'),