docstring edits and additions

cartoframes/auth/__init__.py

@@ -1,5 +1,7 @@
-"""Auth namespace contains the necessary tools to manage authentication by allowing
-the user to set its CARTO credentials."""
+"""Auth namespace contains the class to manage authentication: 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
 
 from .credentials import Credentials

cartoframes/auth/defaults.py

@@ -10,7 +10,12 @@
 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:mod:`cartoframes.viz.helpers`),
+    :py:class:`cartoframes.data.Dataset`,
+    :py:class:`cartoframes.data.clients.SQLClient`, and others.
 
     Args:
 
@@ -22,39 +27,86 @@ def set_default_credentials(
           https://eschbacher.carto.com for user ``eschbacher``) whether on
           a personal or multi-user account. On-premises installation users
           should ask their admin.
-        api_key (str, optional): CARTO API key.
+        api_key (str, optional): CARTO API key. Depending on the application,
+          this can be a project API key or the account master API key.
         username (str, optional): CARTO user name of the account.
         session (requests.Session, optional): requests session. See `requests
           documentation
           <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::
 
             from cartoframes.auth import set_default_credentials
+
             set_default_credentials(
                 username='your_user_name',
                 api_key='your api key'
             )
+
             # or
+
             set_default_credentials(
                 'your_user_name',
                 '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. With this
+        setting, only read-only operations can occur (e.g., no publishing of
+        maps, reading data from the Data Observatory, or creating new hosted
+        datasets).
 
         .. code::
 
             from cartoframes.auth import set_default_credentials
             set_default_credentials('your_user_name')
 
-        From a pair base_url, api_key.
+        From a pair ``base_url``, ``api_key``.
 
         .. code::
 
@@ -69,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,6 +167,28 @@ def set_default_credentials(
 
 
 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

@@ -22,31 +22,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::
 
@@ -58,9 +58,9 @@ class Dataset(object):
                 api_key='your api key'
             )
 
-            Dataset('table_name')
+            ds = Dataset('table_name')
 
-        Query usign CARTO
+        Query against tables in user CARTO account:
 
         .. code::
 
@@ -72,7 +72,7 @@ class Dataset(object):
                 api_key='your api key'
             )
 
-            Dataset('select * from table_name WHERE ...')
+            ds = Dataset('SELECT * FROM table_name JOIN table2 ON ...')
     """
 
     DOWNLOAD_RETRY_TIMES = 3
@@ -83,17 +83,29 @@ def __init__(self, data, credentials=None, schema=None):
 
     @property
     def credentials(self):
-        """Dataset :py:class:`Credentials <cartoframes.auth.Credentials>`"""
+        """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:`Credentials <cartoframes.auth.Credentials>` 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