Merge 530a6a2 into 6f48f72

cartoframes/auth/__init__.py

@@ -1,5 +1,7 @@
 """Auth namespace contains the class to manage authentication: Credentials.
-It also includes the utility method set_default_credentials."""
+It also includes the utility functions
+:func:`cartoframes.auth.set_default_credentials` and 
+:func:`cartoframes.auth.get_default_credentials`."""
 from __future__ import absolute_import
 import re
 
@@ -11,7 +13,11 @@
 def set_default_credentials(
         first=None, second=None, credentials=None,
         username=None, base_url=None, api_key=None, session=None):
-    """set_default_credentials
+    """Set default credentials for all operations that require authentication
+    against a CARTO account. CARTOframes methods :py:class:`cartoframes.viz.Layer`
+    (and helper layers in :py:module:`cartoframes.viz.helpers`),
+    :py:class:`cartoframes.data.Dataset`,
+    :py:class:`cartoframes.data.clients.SQLClient`, and others.
 
     Args:
         credentials (:py:class:`Credentials <cartoframes.credentials.Credentials>`, optional):
@@ -29,9 +35,47 @@ def set_default_credentials(
           <https://2.python-requests.org/en/master/user/advanced/#session-objects>`__
           for more information.
 
+    .. note::
+
+        The recommended way to authenticate in CARTOframes is to read user
+        credentials from a JSON file that is structured like this:
+
+        .. code:: JSON
+
+            {
+                "username": "your user name",
+                "api_key": "your api key",
+                "base_url": "https://your_username.carto.com"
+            }
+
+
+        *Note that the ``base_url`` will be different for on premises
+        installations.*
+
+        By using the :func:`cartoframes.auth.Credentials.save` method, this
+        file will automatically be created for you in a default location
+        depending on your operating system. A custom location can also be
+        specified as an argument to the method.
+
+        This file can then be read in the following ways:
+
+        .. code::
+
+            from cartoframes.auth import Credentials, set_default_credentials
+
+            # attempts to read file from default location if it exists
+            creds = Credentials.from_file()
+
+            # read credentials from specified location
+            creds = Credentials.from_file('./carto-project-credentials.json')
+
+            # set default credentials from file
+            set_default_credentials(Credentials.from_file())
+
+
     Example:
 
-        From a pair username, api_key
+        Create Credentials from a ``username``, ``api_key`` pair.
 
         .. code::
 
@@ -49,16 +93,17 @@ def set_default_credentials(
                 'your api key'
             )
 
-        From a username (for public datasets).
-        The API key `default_public` is used by default.
+        Create credentials from only a ``username`` (only works with public
+        datasets and those marked public with link). If the API key is not
+        provided, the public API key `default_public` is used.
 
         .. code::
 
             from cartoframes.auth import set_default_credentials
 
             set_default_credentials('your_user_name')
 
-        From a pair base_url, api_key.
+        From a ``base_url``, ``api_key`` pair.
 
         .. code::
 
@@ -76,8 +121,8 @@ def set_default_credentials(
                 'your api key'
             )
 
-        From a base_url (for public datasets).
-        The API key `default_public` is used by default.
+        From a ``base_url`` (for public datasets). The API key `default_public`
+        is used by default.
 
         .. code::
 
@@ -115,13 +160,36 @@ def set_default_credentials(
 
     else:
         raise ValueError(
-            'Invalid inputs. Pass a Credentials object, a username and api_key pair or a base_url and api_key pair.')
+            'Invalid inputs. Pass a Credentials object, a username and '
+            'api_key pair or a base_url and api_key pair.')
 
     if session:
         _default_credentials.session = session
 
 
 def get_default_credentials():
+    """Retrieve the default credentials if previously set with
+    :func:`cartoframes.auth.set_default_credentials` in Python session.
+
+    Example:
+
+        Retrieve default credentials.
+
+        .. code::
+
+            from cartoframes.auth import set_default_credentials, get_default_credentials
+
+            set_default_credentials(Credentials.from_file())
+
+            current_creds = get_default_credentials()
+
+    Returns:
+
+        :py:class:`cartoframes.auth.Credentials`: Default credentials
+        previously set in current Python session. `None` will returned if
+        default credentials were not previously set.
+
+    """
     return _default_credentials
 
 

cartoframes/data/dataset/dataset.py

@@ -25,31 +25,31 @@ class Dataset(object):
 
         .. code::
 
-            from pandas
+            import pandas
             from cartoframes.data import Dataset
 
-            df = pandas.DataFrame(...)
-            Dataset(df)
+            df = pandas.read_csv('https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_month.csv')
+            ds = Dataset(df)
 
         GeoDataframe:
 
         .. code::
 
-            from geopandas
+            import geopandas as gpd
             from cartoframes.data import Dataset
 
-            gdf = geopandas.DataFrame(...)
-            Dataset(gdf)
+            gdf = gpd.read_file('https://opendata.arcgis.com/datasets/9485c26e98c6450e9611a2360ece965d_0.geojson')
+            ds = Dataset(gdf)
 
         GeoJSON file:
 
         .. code::
 
             from cartoframes.data import Dataset
 
-            Dataset('path/to/geojsonfile')
+            ds = Dataset('path/to/geojson/file.geojson')
 
-        Table from CARTO
+        Table from CARTO:
 
         .. code::
 
@@ -61,9 +61,9 @@ class Dataset(object):
                 api_key='your api key'
             )
 
-            Dataset('table_name')
+            ds = Dataset('table_name')
 
-        Query usign CARTO stuff
+        Query against tables in user CARTO account:
 
         .. code::
 
@@ -75,7 +75,7 @@ class Dataset(object):
                 api_key='your api key'
             )
 
-            Dataset('select * from table_name WHERE ...')
+            ds = Dataset('SELECT * FROM table_name JOIN table2 ON ...')
     """
 
     FAIL = TableDataset.FAIL
@@ -100,24 +100,36 @@ def _init_strategy(self, data, credentials=None, schema=None):
             if strategy.can_work_with(data):
                 return strategy.create(data, credentials, schema)
 
-        raise ValueError('We can not detect the Dataset type')
+        raise ValueError('Cannot detect Dataset type.')
 
     def _get_strategies_registry(self):
         return StrategiesRegistry()
 
     @property
     def credentials(self):
-        """Dataset :py:class:`Context <cartoframes.auth.Context>`"""
+        """Dataset's :py:class:`Credentials <cartoframes.auth.Credentials>`
+
+        Returns:
+            :py:class:`Credentials <cartoframes.auth.Credentials>`: Credentials,
+            if any, for data associated with Dataset instance.
+
+        """
         return self._strategy.credentials
 
     @credentials.setter
     def credentials(self, credentials):
-        """Set a new :py:class:`Context <cartoframes.auth.Context>` for a Dataset instance."""
+        """Set a new :py:class:`Credentials <cartoframes.auth.Credentials>`
+        for a Dataset instance.
+
+        Args:
+            credentials (:py:class:`cartoframes.auth.Credentials`): Credentials
+              instance to associated with Datset instance
+        """
         self._strategy.credentials = credentials
 
     @property
     def table_name(self):
-        """Dataset table name"""
+        """Dataset table name. If `None`, then the data is a query or DataFrame"""
         return self._strategy.table_name
 
     @property