Merge pull request #297 from CartoDB/v0.4.0b6

v0.4.0b6

Author: andy-esch

README.rst

@@ -1,5 +1,5 @@
 ===========
-CARTOFrames
+CARTOframes
 ===========
 
 .. image:: https://travis-ci.org/CartoDB/cartoframes.svg?branch=master
@@ -12,7 +12,7 @@ CARTOFrames
 
 A Python package for integrating `CARTO <https://carto.com/>`__ maps, analysis, and data services into data science workflows.
 
-Python data analysis workflows often rely on the de facto standards `pandas <http://pandas.pydata.org/>`__ and `Jupyter notebooks <http://jupyter.org/>`__. Integrating CARTO into this workflow saves data scientists time and energy by not having to export datasets as files or retain multiple copies of the data. Instead, CARTOFrames give the ability to communicate reproducible analysis while providing the ability to gain from CARTO's services like hosted, dynamic or static maps and `Data Observatory <https://carto.com/data-observatory/>`__ augmentation.
+Python data analysis workflows often rely on the de facto standards `pandas <http://pandas.pydata.org/>`__ and `Jupyter notebooks <http://jupyter.org/>`__. Integrating CARTO into this workflow saves data scientists time and energy by not having to export datasets as files or retain multiple copies of the data. Instead, CARTOframes give the ability to communicate reproducible analysis while providing the ability to gain from CARTO's services like hosted, dynamic or static maps and `Data Observatory <https://carto.com/data-observatory/>`__ augmentation.
 
 Features
 
@@ -38,7 +38,7 @@ To install `cartoframes` (currently in beta) on your machine, do the following t
 
 .. code:: bash
 
-    $ pip install --pre cartoframes
+    $ pip install cartoframes
 
 It is recommended to use `cartoframes` in Jupyter Notebooks (`pip install jupyter`). See the example usage section below or notebooks in the `examples directory <https://github.com/CartoDB/cartoframes/tree/master/examples>`__ for using `cartoframes` in that environment.
 
@@ -51,7 +51,7 @@ To setup `cartoframes` and `Jupyter` in a `virtual environment <http://python-gu
 
     $ virtualenv venv
     $ source venv/bin/activate
-    (venv) $ pip install --pre cartoframes
+    (venv) $ pip install cartoframes
     (venv) $ pip install jupyter
     (venv) $ jupyter notebook
 

cartoframes/__version__.py

@@ -1 +1 @@
-__version__ = '0.3.0b5'
+__version__ = '0.4.0b6'

cartoframes/context.py

@@ -18,12 +18,12 @@
 from carto.sql import SQLClient, BatchSQLClient
 from carto.exceptions import CartoException
 
-from .credentials import Credentials
-from .dataobs import get_countrytag
-from . import utils
-from .layer import BaseMap
-from .maps import non_basemap_layers, get_map_name, get_map_template
-from .__version__ import __version__
+from cartoframes.credentials import Credentials
+from cartoframes.dataobs import get_countrytag
+from cartoframes import utils
+from cartoframes.layer import BaseMap
+from cartoframes.maps import non_basemap_layers, get_map_name, get_map_template
+from cartoframes.__version__ import __version__
 
 if sys.version_info >= (3, 0):
     from urllib.parse import urlparse, urlencode
@@ -74,9 +74,10 @@ class CartoContext(object):
 
     Args:
         base_url (str): Base URL of CARTO user account. Cloud-based accounts
-            are of the form ``https://{username}.carto.com`` (e.g.,
-            https://eschbacher.carto.com for user ``eschbacher``). On-premises
-            installation users should ask their admin.
+            should use the form ``https://{username}.carto.com`` (e.g.,
+            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): CARTO API key.
         session (requests.Session, optional): requests session. See `requests
             documentation
@@ -186,7 +187,8 @@ def write(self, df, table_name, temp_dir=CACHE_DIR,
                 CARTO account
             table_name (str): Table to write ``df`` to in CARTO.
             temp_dir (str, optional): Directory for temporary storage of data
-                that is sent to CARTO. Default is ``/tmp`` (Unix-like systems).
+                that is sent to CARTO. Defaults are defined by `appdirs
+                <https://github.com/ActiveState/appdirs/blob/master/README.rst>`__.
             overwrite (bool, optional): Behavior for overwriting ``table_name``
                 if it exits on CARTO. Defaults to ``False``.
             lnglat (tuple, optional): lng/lat pair that can be used for
@@ -207,7 +209,9 @@ def write(self, df, table_name, temp_dir=CACHE_DIR,
                 `content_guessing='true'`, a column named 'countries' with
                 country names will be used to generate polygons for each
                 country. To avoid unintended consequences, avoid `file`, `url`,
-                and other similar arguments.
+                and other similar arguments. Note: Combining `privacy` with
+                `overwrite` (defined above) does not currently update the
+                privacy of a dataset: https://github.com/CartoDB/cartoframes/issues/252.
 
         Returns:
             :obj:`BatchJobStatus` or None: If `lnglat` flag is set and the
@@ -1064,15 +1068,16 @@ def data_discovery(self, region, keywords=None, regex=None, time=None,
             For example, setting the region to be United States counties with
             no filter values set will result in many thousands of measures.
 
-        Example:
+        Examples:
 
-        Get all European Union measures that mention ``freight``.
-        .. code::
+            Get all European Union measures that mention ``freight``.
+
+            .. code::
 
-            meta = cc.data_discovery('European Union',
-                                     keywords='freight',
-                                     time='2010')
-            print(meta['numer_name'].values)
+                meta = cc.data_discovery('European Union',
+                                         keywords='freight',
+                                         time='2010')
+                print(meta['numer_name'].values)
 
         Arguments:
             region (str or list of float): Information about the region of
@@ -1319,14 +1324,15 @@ def data(self, table_name, metadata, persist_as=None, how='the_geom'):
             persist_as (str, optional): Output the results of augmenting
                 `table_name` to `persist_as` as a persistent table on CARTO.
                 Defaults to ``None``, which will not create a table.
-            how (str, optional): Column name for identifying the geometry from
-                which to fetch the data. Defaults to `the_geom`, which results
-                in measures that are spatially interpolated (e.g., a
-                neighborhood boundary's population will be calculated from
-                underlying census tracts). Specifying a column that has the
-                geometry identifier (for example, GEOID for US Census
-                boundaries), results in measures directly from the Census for
-                that GEOID but normalized how it is specified in the metadata.
+            how (str, optional): **Not fully implemented**. Column name for
+                identifying the geometry from which to fetch the data. Defaults
+                to `the_geom`, which results in measures that are spatially
+                interpolated (e.g., a neighborhood boundary's population will
+                be calculated from underlying census tracts). Specifying a
+                column that has the geometry identifier (for example, GEOID for
+                US Census boundaries), results in measures directly from the
+                Census for that GEOID but normalized how it is specified in the
+                metadata.
 
         Returns:
             pandas.DataFrame: A DataFrame representation of `table_name` which

docs/_sources/cartoframes.dataobs.rst.txt

@@ -0,0 +1,7 @@
+cartoframes\.dataobs module
+===========================
+
+.. automodule:: cartoframes.dataobs
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/_sources/cartoframes.rst.txt

@@ -8,6 +8,7 @@ Submodules
 
    cartoframes.context
    cartoframes.credentials
+   cartoframes.dataobs
    cartoframes.layer
    cartoframes.maps
    cartoframes.styling

docs/_sources/index.rst.txt

@@ -7,18 +7,15 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
-   modules
-
-CARTOFrames Functionality
+CARTOframes Functionality
 =========================
 
 CartoContext
 ------------
 .. autoclass:: context.CartoContext
     :member-order: bysource
-    :members: read, query, delete, map, data_augment
+    :members: read, query, delete, map, data_discovery, data
 
     .. automethod:: write(df, table_name, temp_dir=SYSTEM_TMP_PATH, overwrite=False, lnglat=None, encode_geom=False, geom_col=None, \*\*kwargs)