superset-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ville...@apache.org
Subject [incubator-superset] branch master updated: Improve documentation (#7813)
Date Wed, 03 Jul 2019 16:54:16 GMT
This is an automated email from the ASF dual-hosted git repository.

villebro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-superset.git


The following commit(s) were added to refs/heads/master by this push:
     new 0125ba4  Improve documentation (#7813)
0125ba4 is described below

commit 0125ba40ef31790fddbd8cd156e9d39ce532c051
Author: Ville Brofeldt <33317356+villebro@users.noreply.github.com>
AuthorDate: Wed Jul 3 19:54:03 2019 +0300

    Improve documentation (#7813)
    
    * Improve documentation and add type annotations for jinja context
    
    * Fix linting errors
    
    * Move requirements to correct place and remove redundant line change
    
    * Make example query more ANSI SQL
---
 docs/conf.py              |  1 +
 docs/installation.rst     | 14 ++++++++++++--
 docs/requirements.txt     |  5 +++--
 docs/sqllab.rst           | 11 +++++++++--
 superset/jinja_context.py | 36 ++++++++++++++++++------------------
 5 files changed, 43 insertions(+), 24 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 80d6de1..f9fea9f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,6 +47,7 @@ import sphinx_rtd_theme
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinx_autodoc_typehints',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/installation.rst b/docs/installation.rst
index f31c34b..37991de 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -377,7 +377,7 @@ Here's a list of some of the recommended packages.
 +------------------+---------------------------------------+-------------------------------------------------+
 | ClickHouse       | ``pip install sqlalchemy-clickhouse`` |                            
                    |
 +------------------+---------------------------------------+-------------------------------------------------+
-| Google Sheets    | ``pip install gsheetsdb``             | ``gsheets://`              
                    |
+| Google Sheets    | ``pip install gsheetsdb``             | ``gsheets://``             
                    |
 +------------------+---------------------------------------+-------------------------------------------------+
 | IBM Db2          | ``pip install ibm_db_sa``             | ``db2+ibm_db://``          
                    |
 +------------------+---------------------------------------+-------------------------------------------------+
@@ -423,6 +423,15 @@ You can also use `PyAthena` library(no java required) like this ::
 
 See `PyAthena <https://github.com/laughingman7743/PyAthena#sqlalchemy>`_.
 
+(Google) BigQuery
+-----------------
+
+The connection string for BigQuery looks like this ::
+
+    bigquery://{project_id}
+
+To be able to upload data, e.g. sample data, the python library `pandas_gbq` is required.
+
 Snowflake
 ---------
 
@@ -458,7 +467,7 @@ Required environment variables: ::
 See `Teradata SQLAlchemy <https://github.com/Teradata/sqlalchemy-teradata>`_.
 
 Apache Drill
----------
+------------
 At the time of writing, the SQLAlchemy Dialect is not available on pypi and must be downloaded
here:
 `SQLAlchemy Drill <https://github.com/JohnOmernik/sqlalchemy-drill>`_
 
@@ -850,6 +859,7 @@ You can configure which validation implementation is used with which database
 engine by adding a block like the following to your config.py:
 
 .. code-block:: python
+
      FEATURE_FLAGS = {
          'SQL_VALIDATORS_BY_ENGINE': {
              'presto': 'PrestoDBSQLValidator',
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 5761bdf..113860b 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -14,5 +14,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-sphinx==1.8.1
-sphinx-rtd-theme==0.3.1
+sphinx==2.1.2
+sphinx_autodoc_typehints==1.6.0
+sphinx-rtd-theme==0.4.3
diff --git a/docs/sqllab.rst b/docs/sqllab.rst
index 6d12971..5fe24ad 100644
--- a/docs/sqllab.rst
+++ b/docs/sqllab.rst
@@ -79,13 +79,20 @@ Superset's Jinja context:
 
 `Jinja's builtin filters <http://jinja.pocoo.org/docs/dev/templates/>`_ can be also
be applied where needed.
 
-.. autoclass:: superset.jinja_context.PrestoTemplateProcessor
-    :members:
+.. autofunction:: superset.jinja_context.current_user_id
+
+.. autofunction:: superset.jinja_context.current_username
 
 .. autofunction:: superset.jinja_context.url_param
 
 .. autofunction:: superset.jinja_context.filter_values
 
+.. autoclass:: superset.jinja_context.PrestoTemplateProcessor
+    :members:
+
+.. autoclass:: superset.jinja_context.HiveTemplateProcessor
+    :members:
+
 Extending macros
 ''''''''''''''''
 
diff --git a/superset/jinja_context.py b/superset/jinja_context.py
index a72d9a1..cfb7593 100644
--- a/superset/jinja_context.py
+++ b/superset/jinja_context.py
@@ -21,6 +21,7 @@ import inspect
 import json
 import random
 import time
+from typing import Any, List, Optional, Tuple
 import uuid
 
 from dateutil.relativedelta import relativedelta
@@ -41,7 +42,7 @@ BASE_CONTEXT = {
 BASE_CONTEXT.update(config.get("JINJA_CONTEXT_ADDONS", {}))
 
 
-def url_param(param, default=None):
+def url_param(param: str, default: Optional[str] = None) -> Optional[Any]:
     """Read a url or post parameter and use it in your SQL Lab query
 
     When in SQL Lab, it's possible to add arbitrary URL "query string"
@@ -56,33 +57,34 @@ def url_param(param, default=None):
     it should carry through to your queries.
 
     :param param: the parameter to lookup
-    :type param: str
     :param default: the value to return in the absence of the parameter
-    :type default: str
     """
     if request.args.get(param):
         return request.args.get(param, default)
     # Supporting POST as well as get
-    if request.form.get("form_data"):
-        form_data = json.loads(request.form.get("form_data"))
+    form_data = request.form.get("form_data")
+    if isinstance(form_data, str):
+        form_data = json.loads(form_data)
         url_params = form_data.get("url_params") or {}
         return url_params.get(param, default)
     return default
 
 
-def current_user_id():
+def current_user_id() -> Optional[int]:
     """The id of the user who is currently logged in"""
     if hasattr(g, "user") and g.user:
         return g.user.id
+    return None
 
 
-def current_username():
+def current_username() -> Optional[str]:
     """The username of the user who is currently logged in"""
     if g.user:
         return g.user.username
+    return None
 
 
-def filter_values(column, default=None):
+def filter_values(column: str, default: Optional[str] = None) -> List[str]:
     """ Gets a values for a particular filter as a list
 
     This is useful if:
@@ -91,20 +93,18 @@ def filter_values(column, default=None):
         - you want to have the ability for filter inside the main query for speed
           purposes
 
-    This searches for "filters" and "extra_filters" in form_data for a match
+    This searches for "filters" and "extra_filters" in ``form_data`` for a match
+
+    Usage example::
 
-    Usage example:
         SELECT action, count(*) as times
         FROM logs
         WHERE action in ( {{ "'" + "','".join(filter_values('action_type')) + "'" }} )
-        GROUP BY 1
+        GROUP BY action
 
     :param column: column/filter name to lookup
-    :type column: str
     :param default: default value to return if there's no matching columns
-    :type default: str
     :return: returns a list of filter values
-    :type: list
     """
     form_data = json.loads(request.form.get("form_data", "{}"))
     return_val = []
@@ -144,7 +144,7 @@ class BaseTemplateProcessor(object):
     name. For globally available methods use ``@classmethod``.
     """
 
-    engine = None
+    engine: Optional[str] = None
 
     def __init__(self, database=None, query=None, table=None, **kwargs):
         self.database = database
@@ -167,7 +167,7 @@ class BaseTemplateProcessor(object):
             self.context[self.engine] = self
         self.env = SandboxedEnvironment()
 
-    def process_template(self, sql, **kwargs):
+    def process_template(self, sql: str, **kwargs) -> str:
         """Processes a sql template
 
         >>> sql = "SELECT '{{ datetime(2017, 1, 1).isoformat() }}'"
@@ -189,12 +189,12 @@ class PrestoTemplateProcessor(BaseTemplateProcessor):
     engine = "presto"
 
     @staticmethod
-    def _schema_table(table_name, schema):
+    def _schema_table(table_name: str, schema: str) -> Tuple[str, str]:
         if "." in table_name:
             schema, table_name = table_name.split(".")
         return table_name, schema
 
-    def latest_partition(self, table_name):
+    def latest_partition(self, table_name: str):
         table_name, schema = self._schema_table(table_name, self.schema)
         return self.database.db_engine_spec.latest_partition(
             table_name, schema, self.database


Mime
View raw message