[ Docs - Guides ]

cartoframes/auth/credentials.py

@@ -1,4 +1,4 @@
-"""Credentials management for cartoframes usage."""
+"""Credentials management for CARTOframes usage."""
 
 import json
 import os
@@ -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(cls, 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(cls, 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

@@ -24,7 +24,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. Depending on the application,
@@ -83,14 +83,14 @@ 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'
             )
 
@@ -104,20 +104,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'
             )
 
@@ -127,15 +127,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)

cartoframes/data/observatory/catalog/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>

docs/developer-center/guides/02-Install-CARTOframes-in-your-Notebooks.md

@@ -0,0 +1,55 @@
+## Install CARTOframes in your Notebooks
+
+This guide is intended for those who are going to start using CARTOframes and gives some instructions to install CARTOframes **locally**, in a **Jupyter Notebook** and using a **Virtual Environment**.
+
+### Install CARTOframes using `pip`
+
+It is possible to install CARTOframes with [`pip`](https://pypi.org/project/pip/) by simply typing the following in the command line to do a system install:
+
+```bash
+$ pip install cartoframes
+```
+
+To install a specific version, for example, let's say the 1.2.3 version:
+
+```bash
+$ pip install cartoframes==1.2.3
+```
+
+To install a pre release, use the `--pre` flag:
+
+```bash
+$ pip install cartoframes --pre
+```
+
+### Install CARTOframes in a Jupyter Notebook
+
+In this documentation, all the examples are in a [Jupyter Notebook](https://jupyter.org/). It is recommended to read the [beginner documentation](https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html) to get familiar with Jupyter. To install through a Jupyter Notebook, run this command:
+
+```bash
+! pip install cartoframes
+```
+
+### Use a Virtual Environment
+
+It is recommended to install CARTOframes in a [Virtual Environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/), since they are very useful when working with Python locally. This section provides the necessary information to create a simple Virtual Environment and install CARTOframes in there:
+
+```bash
+$ virtualenv cartoframes_env
+$ source cartoframes_env/bin/activate
+(cartoframes_env) $ pip install cartoframes
+```
+
+To install a specific version:
+
+```bash
+$ virtualenv cartoframes_env
+$ source cartoframes_env/bin/activate
+(cartoframes_env) $ pip install cartoframes==1.2.3
+```
+
+When the virtual environment is activated, it is visible in the command line prompt, in this case: `(cartoframes_env)`. It can be deactivated by typing `deactivate` to exit the virtualenv:
+
+```bash
+(cartoframes_env) $ deactivate
+```

docs/developer-center/guides/03-Login-to-CARTO-Platform.md

@@ -0,0 +1,76 @@
+## Login to CARTO Platform
+
+In this guide, our purpose is to focus on the basics of authentication in CARTOframes. There's a full [Authorization Fundamentals](https://carto.com/developers/fundamentals/authorization/) at CARTO guide to understand how to configure and manage API Keys.
+
+> To use CARTOframes is not *always* needed to be authenticated.
+
+It is needed to set up the user credentials to use Data Services, Data Enrichment or the Data Observatory, between others. In these cases, it's required to have a [CARTO account](https://carto.com/signup/). Once the user has created an account, the credentials can be found at **http://johnsmith.carto.com/your_apps.** for user `johnsmith`, and it should be a **Master** API Key:
+
+![Master API Key - CARTO Dashboard](../../img/guides/credentials/api-keys.png)
+
+All user accounts have a `default_public` API Key to access **public** data.
+
+### Credential parameters
+
+- `username`: your CARTO account username
+- `base_url`: Base URL used for API calls. This is usually of the form `https://johnsmith.carto.com/` for user `johnsmith`. On premises installation (and others) have a different URL pattern.
+- `api_key`: API Key of user's CARTO account. If the data is to be accessed is **public**, it can be set to `default_public`.
+
+### Default Credentials
+
+With [set_default_credentials](/developers/cartoframes/reference/#cartoframes-auth-set_default_credentials), the same user's authentication will be used by _all_ layers and sources by default.
+
+```py
+from cartoframes.auth import set_default_credentials
+
+set_default_credentials(
+    username='johnsmith',
+    api_key='1a2b3c4d5e6f7g8h'
+)
+```
+
+Credentials can be also set by using the `base_url` parameter, which is useful when having an **On premise** or a custom installation:
+
+```py
+from cartoframes.auth import set_default_credentials
+
+set_default_credentials(
+    base_url='https://johnsmith.carto.com/',
+    api_key='1a2b3c4d5e6f7g8h'
+)
+```
+
+When the data is public, the `api_key` parameter isn't required: it's automatically set to `default_public`:
+
+```py
+from cartoframes.auth import set_default_credentials
+
+set_default_credentials('johnsmith')
+```
+
+### Specific Credentials
+
+Instead of setting credentials generally, it is possible to assign specific and different credentials for a Map, Dataset, Layer or Source, between others.
+
+```py
+from cartoframes.auth import Credentials
+from cartoframes.data import Dataset
+
+dataset = Dataset('dataset', credentials=Credentials('johnsmith', '1a2b3c4d5e6f7g8h'))
+```
+
+### The config file
+
+Credentials can be stored in a **configuration file** with the following format:
+
+Example `config.json` file:
+
+```json
+{
+  "APIKEY": "",
+  "USERNAME": "",
+  "USERURL": "https://{username}.carto.com/"
+}
+```
+
+The filename is `cartocreds.json` by default, but it can be overwriten. There are [different methods](/developers/cartoframes/reference/#cartoframes-auth-Credentials) to read, update and delete your credentials.