[ Docs - Guides ]

cartoframes/auth/credentials.py

@@ -1,4 +1,4 @@
-"""Credentials management for cartoframes usage."""
+"""Credentials management for CARTOframes usage."""
 
 import os
 import sys
@@ -28,16 +28,18 @@ class Credentials(object):
     """Credentials class for managing and storing user CARTO credentials. The
     arguments are listed in order of precedence: :obj:`Credentials` instances
     are first, `key` and `base_url`/`username` are taken next, and
-    `config_file` (if given) is taken last. If no arguments are passed, then
-    there will be an attempt to retrieve credentials from a previously saved
-    session. One of the above scenarios needs to be met to successfully
+    `config_file` (if given) is taken last. The config file is `cartocreds.json`
+    by default. If no arguments are passed, then there will be an attempt to
+    retrieve credentials from a previously saved session.
+    One of the above scenarios needs to be met to successfully
     instantiate a :obj:`Credentials` object.
 
     Args:
-        api_key (str, optional): API key of user's CARTO account
+        api_key (str, optional): API key of user's CARTO account. If the dataset is
+            public, it can be set to 'default_public'.
         username (str, optional): Username of CARTO account
         base_url (str, optional): Base URL used for API calls. This is usually
-            of the form `https://eschbacher.carto.com/` for user `eschbacher`.
+            of the form `https://johnsmith.carto.com/` for user `johnsmith`.
             On premises installations (and others) have a different URL
             pattern.
         session (requests.Session, optional): requests session. See `requests
@@ -47,10 +49,12 @@ class Credentials(object):
 
     Example:
 
+        Setting basic credentials:
+
         .. code::
 
             from cartoframes.auth import Credentials
-            credentials = Credentials(username='eschbacher', api_key='abcdefg')
+            credentials = Credentials(username='johnsmith', api_key='abcdefg')
 
     """
 
@@ -145,7 +149,7 @@ def save(self, config_file=None):
         """Saves current user credentials to user directory.
 
         Args:
-            config_loc (str, optional): Location where credentials are to be
+            config_file (str, optional): Location where credentials are to be
                 stored. If no argument is provided, it will be send to the
                 default location.
 
@@ -154,13 +158,13 @@ def save(self, config_file=None):
             .. code::
 
                 from cartoframes.auth import Credentials
-                credentials = Credentials(username='eschbacher', api_key='abcdefg')
+                credentials = Credentials(username='johnsmith', api_key='abcdefg')
                 credentials.save()  # save to default location
 
             .. code::
 
                 from cartoframes.auth import Credentials
-                credentials = Credentials(username='eschbacher', api_key='abcdefg')
+                credentials = Credentials(username='johnsmith', api_key='abcdefg')
                 credentials.save('path/to/credentials/file')
         """
 
@@ -177,7 +181,8 @@ def save(self, config_file=None):
     @classmethod
     def delete(self, config_file=None):
         """Deletes the credentials file specified in `config_file`. If no
-        file is specified, it deletes the default user credential file.
+        file is specified, it deletes the default user credential file
+        (`cartocreds.json`)
 
         Args:
 
@@ -191,19 +196,22 @@ def delete(self, config_file=None):
 
                 >>> credentials = Credentials.from_file()
                 >>> print(credentials)
-                Credentials(username='eschbacher', api_key='abcdefg',
-                    base_url='https://eschbacher.carto.com/')
+                Credentials(username='johnsmith', api_key='abcdefg',
+                    base_url='https://johnsmith.carto.com/')
 
         """
 
         path_to_remove = config_file or _DEFAULT_PATH
+
         try:
             os.remove(path_to_remove)
             warnings.warn('Credentials at {} successfully removed.'.format(path_to_remove))
         except OSError:
             warnings.warn('No credential file found at {}.'.format(path_to_remove))
 
     def get_do_token(self):
+        """Returns the Data Observatory v2 token"""
+
         do_token_manager = DoTokenManager(self.get_api_key_auth_client())
         token = do_token_manager.get()
         if not token:

cartoframes/auth/defaults.py

@@ -19,7 +19,7 @@ def set_default_credentials(
           instance can be used in place of a `username | base_url`/`api_key` combination.
         base_url (str, optional): Base URL of CARTO user account. Cloud-based accounts
           should use the form ``https://{username}.carto.com`` (e.g.,
-          https://eschbacher.carto.com for user ``eschbacher``) whether on
+          https://johnsmith.carto.com for user ``johnsmith``) whether on
           a personal or multi-user account. On-premises installation users
           should ask their admin.
         api_key (str, optional): CARTO API key.
@@ -37,12 +37,12 @@ def set_default_credentials(
 
             from cartoframes.auth import set_default_credentials
             set_default_credentials(
-                username='your_user_name',
+                username='johnsmith',
                 api_key='your api key'
             )
             # or
             set_default_credentials(
-                'your_user_name',
+                'johnsmith',
                 'your api key'
             )
 
@@ -52,20 +52,20 @@ def set_default_credentials(
         .. code::
 
             from cartoframes.auth import set_default_credentials
-            set_default_credentials('your_user_name')
+            set_default_credentials('johnsmith')
 
         From a pair base_url, api_key.
 
         .. code::
 
             from cartoframes.auth import set_default_credentials
             set_default_credentials(
-                base_url='https://your_user_name.carto.com',
+                base_url='https://johnsmith.carto.com',
                 api_key='your api key'
             )
             # or
             set_default_credentials(
-                'https://your_user_name.carto.com',
+                'https://johnsmith.carto.com',
                 'your api key'
             )
 
@@ -75,15 +75,15 @@ def set_default_credentials(
         .. code::
 
             from cartoframes.auth import set_default_credentials
-            set_default_credentials('https://your_user_name.carto.com')
+            set_default_credentials('https://johnsmith.carto.com')
 
         From a :py:class:`Credentials <cartoframes.auth.Credentials>` class.
 
         .. code::
 
             from cartoframes.auth import Credentials, set_default_credentials
             credentials = Credentials(
-                base_url='https://your_user_name.carto.com',
+                base_url='https://johnsmith.carto.com',
                 api_key='your api key'
             )
             set_default_credentials(credentials)
@@ -115,6 +115,12 @@ def set_default_credentials(
 
 
 def get_default_credentials():
+    """get_default_credentials
+
+    Returns:
+        :obj:`Credentials`: The credentials that have been set by default.
+
+    """
     return _default_credentials
 
 

cartoframes/data/observatory/catalog.py

@@ -6,7 +6,7 @@
 from .country import Country
 from .geography import Geography
 from .subscriptions import Subscriptions
-from .repository.constants import COUNTRY_FILTER, CATEGORY_FILTER, GEOGRAPHY_FILTER
+from .repository.constants import COUNTRY_FILTER, CATEGORY_FILTER, GEOGRAPHY_FILTER, PROVIDER_FILTER
 
 from ...auth import Credentials, defaults
 
@@ -112,6 +112,21 @@ def geography(self, geography_id):
         self.filters[GEOGRAPHY_FILTER] = filter_value
         return self
 
+    def provider(self, provider_id):
+        """Add a provider filter to the current Catalog instance
+
+        Args:
+            provider_id (str):
+              Id value of the provider to be used for filtering the Catalog.
+
+        Returns:
+            :py:class:`CatalogList <cartoframes.data.observatory.entity.CatalogList>`
+
+        """
+
+        self.filters[PROVIDER_FILTER] = provider_id
+        return self
+
     def clear_filters(self):
         """Remove the current filters from this Catalog instance."""
 

docs/developer-center/guides/01-Introduction.md

@@ -0,0 +1,39 @@
+## Introduction
+
+Use these guides to learn about integrating CARTOframes into your data science workflows. Working inside of a Jupyter Notebook, the guides walk through initial set-up and installation, login to CARTO platform, reading data from CARTO into your Python session, writing data to your CARTO account, and the basics of visualizing your data on a map.
+
+If you're already familiar with Jupyter Notebooks, you can also take a look to our [Notebook Examples](/developers/cartoframes/examples) for more detailed use cases.
+
+### Content
+
+<div class="doc-guides__cartoframes-row">
+  <div class="doc-guides__cartoframes-block">
+    <span class="doc-guides__title">
+      <a href="/developers/cartoframes/guides/Install-CARTOframes-in-your-Notebooks/">Installation</a>
+    </span>
+    <p class="doc-guides__description">This guide walks you through the process of installing CARTOframes in a Jupyter Notebook</p>
+  </div>
+
+  <div class="doc-guides__cartoframes-block">
+    <span class="doc-guides__title">
+      <a href="/developers/cartoframes/guides/Login-to-CARTO-Platform/">Login into CARTO</a>
+    </span>
+    <p class="doc-guides__description">Learn how to authenticate against CARTO</p>
+  </div>
+</div>
+
+<div class="doc-guides__cartoframes-row">
+  <div class="doc-guides__cartoframes-block">
+    <span class="doc-guides__title">
+      <a href="/developers/cartoframes/guides/Quickstart-Part-1/">Quickstart Part 1</a>
+    </span>
+    <p class="doc-guides__description">From import to first visualization</p>
+  </div>
+
+  <div class="doc-guides__cartoframes-block">
+    <span class="doc-guides__title">
+      <a href="/developers/cartoframes/guides/Quickstart-Part-2/">Quickstart Part 2</a>
+    </span>
+    <p class="doc-guides__description">From analysis to share a visualization</p>
+  </div>
+</div>