Repository: ibis-project/ibis

Issue:
Improve docstrings for hdfs_connect and impala_connect
@laserson can you take a crack at these?



Discussion:
Moving beyond 0.3

whoops, totally missed this issue

The interface for connecting to Impala will change a bit when cloudera/impyla#97 gets merged in, which will probably only happen next week.

sounds good, thanks

Are we ready to cut a new release of impyla?  I'd like to get that interface change released so we can have it reflect here.

I think we're ready to release impyla

k, I'll do it later today

let's make one last pass then close this


Resolving patch:
diff --git a/ibis/__init__.py b/ibis/__init__.py
--- a/ibis/__init__.py
+++ b/ibis/__init__.py
@@ -77,18 +77,19 @@ def hdfs_connect(host='localhost', port=50070, protocol='webhdfs',
 
     Parameters
     ----------
-    host : string
-    port : int, default 50070 (webhdfs default)
+    host : string, Host name of the HDFS NameNode
+    port : int, NameNode's WebHDFS port (default 50070)
     protocol : {'webhdfs'}
-    auth_mechanism : {'NOSASL' <- default, 'GSSAPI', 'LDAP', 'PLAIN'}
-    verify : boolean, default False
-        Set to False to turn off verifying SSL certificates
+    auth_mechanism : string, Set to NOSASL or PLAIN for non-secure clusters.
+        Set to GSSAPI or LDAP for Kerberos-secured clusters.
+    verify : boolean, Set to False to turn off verifying SSL certificates.
+        (default True)
 
     Other keywords are forwarded to hdfs library classes
 
     Returns
     -------
-    client : ibis HDFS client
+    client : WebHDFS
     """
     import requests
     session = kwds.setdefault('session', requests.Session())
diff --git a/ibis/impala/api.py b/ibis/impala/api.py
--- a/ibis/impala/api.py
+++ b/ibis/impala/api.py
@@ -23,20 +23,27 @@ def connect(host='localhost', port=21050, database='default', timeout=45,
             auth_mechanism='NOSASL', kerberos_service_name='impala',
             pool_size=8, hdfs_client=None):
     """
-    Create an Impala Client for use with Ibis
+    Create an ImpalaClient for use with Ibis.
 
     Parameters
     ----------
-    host : host name
-    port : int, default 21050 (HiveServer 2)
-    database :
-    timeout :
-    use_ssl : boolean
-    ca_cert :
-    user :
-    password :
-    auth_mechanism : {'NOSASL' <- default, 'PLAIN', 'GSSAPI', 'LDAP'}
-    kerberos_service_name : string, default 'impala'
+    host : string, Host name of the impalad or HiveServer2 in Hive
+    port : int, Defaults to 21050 (Impala's HiveServer2)
+    database : string, Default database when obtaining new cursors
+    timeout : int, Connection timeout (seconds) when communicating with
+        HiveServer2
+    use_ssl : boolean, Use SSL when connecting to HiveServer2
+    ca_cert : string, Local path to 3rd party CA certificate or copy of server
+        certificate for self-signed certificates. If SSL is enabled, but this
+        argument is None, then certificate validation is skipped.
+    user : string, LDAP user to authenticate
+    password : string, LDAP password to authenticate
+    auth_mechanism : string, {'NOSASL' <- default, 'PLAIN', 'GSSAPI', 'LDAP'}.
+        Use NOSASL for non-secured Impala connections.  Use PLAIN for
+        non-secured Hive clusters.  Use LDAP for LDAP authenticated
+        connections.  Use GSSAPI for Kerberos-secured clusters.
+    kerberos_service_name : string, Specify particular impalad service
+        principal.
 
     Examples
     --------


Test patch: