singlestoredb 0.3.3__py3-none-any.whl → 1.0.3__py3-none-any.whl

singlestoredb/__init__.py

@@ -12,9 +12,10 @@ Examples
 ...     print(row)
 
 """
-from __future__ import annotations
 
-__version__ = '0.3.3'
+__version__ = '1.0.3'
+
+from typing import Any
 
 from .config import options, get_option, set_option, describe_option
 from .connection import connect, apilevel, threadsafety, paramstyle
@@ -30,3 +31,33 @@ from .types import (
     Date, Time, Timestamp, DateFromTicks, TimeFromTicks, TimestampFromTicks,
     Binary, STRING, BINARY, NUMBER, DATETIME, ROWID,
 )
+
+
+#
+# This function is defined here to prevent the side-effect of
+# attempting to load the SQLAlchemy dialect in the core SDK.
+#
+def create_engine(*args: Any, **kwargs: Any) -> Any:
+    """
+    Create an SQLAlchemy engine for SingleStoreDB.
+
+    Parameters
+    ----------
+    **kwargs : Any
+        The parameters taken here are the same as for
+        `sqlalchemy.create_engine`. However, this function can be
+        called without any parameters in order to inherit parameters
+        set by environment variables or parameters set in by
+        options in Python code.
+
+    See Also
+    --------
+    `sqlalchemy.create_engine`
+
+    Returns
+    -------
+    SQLAlchemy engine
+
+    """
+    from .alchemy import create_engine
+    return create_engine(*args, **kwargs)

singlestoredb/alchemy/__init__.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+import inspect
+from typing import Any
+from urllib.parse import quote
+
+try:
+    import sqlalchemy
+    from sqlalchemy_singlestoredb import *  # noqa: F403, F401
+    has_sqlalchemy = True
+except ImportError:
+    import warnings
+    warnings.warn(
+        'sqlalchemy_singlestoredb must be installed to use this module',
+        RuntimeWarning,
+    )
+    has_sqlalchemy = False
+
+from ..connection import build_params
+from ..connection import connect
+
+
+def create_engine(*args: Any, **kwargs: Any) -> Any:
+    """
+    Create an SQLAlchemy engine for SingleStoreDB.
+
+    Parameters
+    ----------
+    **kwargs : Any
+        The parameters taken here are the same as for
+        `sqlalchemy.create_engine`. However, this function can be
+        called without any parameters in order to inherit parameters
+        set by environment variables or parameters set in by
+        options in Python code.
+
+    See Also
+    --------
+    `sqlalchemy.create_engine`
+
+    Returns
+    -------
+    SQLAlchemy engine
+
+    """
+    if not has_sqlalchemy:
+        raise RuntimeError('sqlalchemy_singlestoredb package is not installed')
+
+    if len(args) > 1:
+        raise ValueError(
+            '`args` can only have a single element '
+            'containing the database URL',
+        )
+
+    if args:
+        kwargs['host'] = args[0]
+
+    conn_params = {}
+    sa_params = {}
+
+    conn_args = inspect.getfullargspec(connect).args
+
+    for key, value in kwargs.items():
+        if key in conn_args:
+            conn_params[key] = value
+        else:
+            sa_params[key] = value
+
+    params = build_params(**conn_params)
+    driver = params.pop('driver', None)
+    host = params.pop('host')
+    port = params.pop('port')
+    user = params.pop('user', None)
+    password = params.pop('password', None)
+    database = params.pop('database', '')
+
+    if not driver:
+        driver = 'singlestoredb+mysql'
+    elif not driver.startswith('singlestoredb'):
+        driver = f'singlestoredb+{driver}'
+
+    if user is not None and password is not None:
+        url = f'{driver}://{quote(user)}:{quote(password)}@' \
+              f'{host}:{port}/{quote(database)}'
+    elif user is not None:
+        url = f'{driver}://{quote(user)}@{host}:{port}/{quote(database)}'
+    elif password is not None:
+        url = f'{driver}://:{quote(password)}@{host}:{port}/{quote(database)}'
+    else:
+        url = f'{driver}://{host}:{port}/{quote(database)}'
+
+    return sqlalchemy.create_engine(url, connect_args=params, **sa_params)

singlestoredb/auth.py

@@ -1,6 +1,4 @@
 #!/usr/bin/env python
-from __future__ import annotations
-
 import datetime
 from typing import Any
 from typing import List
@@ -42,7 +40,7 @@ class JSONWebToken(object):
         self.timeout = timeout
 
     @classmethod
-    def from_token(cls, token: bytes, verify_signature: bool = False) -> JSONWebToken:
+    def from_token(cls, token: bytes, verify_signature: bool = False) -> 'JSONWebToken':
         """Validate the contents of the JWT."""
         info = jwt.decode(token, options={'verify_signature': verify_signature})
 
@@ -185,10 +183,14 @@ def get_jwt(
         server = HTTPServer(('127.0.0.1', 0), AuthServer)
         threading.Thread(target=server.serve_forever).start()
 
+        host = server.server_address[0]
+        if isinstance(host, bytes):
+            host = host.decode('utf-8')
+
         query = urllib.parse.urlencode({
             k: v for k, v in dict(
                 email=email,
-                returnTo=f'http://{server.server_address[0]}:{server.server_address[1]}',
+                returnTo=f'http://{host}:{server.server_address[1]}',
                 db=_listify(databases),
                 cluster=_listify(clusters),
             ).items() if v is not None

singlestoredb/config.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python
 """SingleStoreDB package options."""
-from __future__ import annotations
-
 import functools
 
 from . import auth
 from .utils.config import check_bool  # noqa: F401
+from .utils.config import check_dict_str_str  # noqa: F401
 from .utils.config import check_float  # noqa: F401
 from .utils.config import check_int  # noqa: F401
+from .utils.config import check_optional_bool  # noqa: F401
 from .utils.config import check_str  # noqa: F401
 from .utils.config import check_url  # noqa: F401
 from .utils.config import describe_option  # noqa: F401
@@ -55,7 +55,7 @@ register_option(
 )
 
 register_option(
-    'driver', 'string', check_str, 'pymysql',
+    'driver', 'string', check_str, 'mysql',
     'Specifies the Python DB-API module to use for communicating'
     'with the database.',
     environ='SINGLESTOREDB_DRIVER',
@@ -68,8 +68,13 @@ register_option(
 )
 
 register_option(
-    'pure_python', 'bool', check_bool, False,
-    'Should the driver use a pure Python implementation?',
+    'pure_python', 'bool', check_optional_bool, None,
+    'Should the driver use a pure Python implementation? If the value is '
+    '`None`, the C extension will be used if it exists, and pure python '
+    'will be used otherwise. If the value is `False`, the pure python '
+    'implementation will be used. If the value is `True` and the C extension '
+    'exists, it will be used. If the value is `True` and the C extension '
+    'doesn\'t exist or can\'t be loaded, a `NotSupportedError` is raised.',
     environ='SINGLESTOREDB_PURE_PYTHON',
 )
 
@@ -79,6 +84,12 @@ register_option(
     environ='SINGLESTOREDB_CHARSET',
 )
 
+register_option(
+    'encoding_errors', 'string', check_str, 'strict',
+    'Specifies the error handling behavior for decoding string values.',
+    environ='SINGLESTOREDB_ENCODING_ERRORS',
+)
+
 register_option(
     'local_infile', 'bool', check_bool, False,
     'Should it be possible to load local files?',
@@ -86,9 +97,9 @@ register_option(
 )
 
 register_option(
-    'odbc_driver', 'str', check_str, 'SingleStore ODBC 1.0 Unicode Driver',
-    'Name of the ODBC driver for ODBC connections',
-    environ='SINGLESTOREDB_ODBC_DRIVER',
+    'multi_statements', 'bool', check_bool, False,
+    'Should it be possible use multiple statements in one query?',
+    environ='SINGLESTOREDB_MULTI_STATEMENTS',
 )
 
 register_option(
@@ -121,6 +132,28 @@ register_option(
     environ='SINGLESTOREDB_SSL_DISABLED',
 )
 
+register_option(
+    'ssl_verify_cert', 'bool', check_optional_bool, None,
+    'Verify the server\'s certificate',
+    environ='SINGLESTOREDB_SSL_VERIFY_CERT',
+)
+
+register_option(
+    'ssl_verify_identity', 'bool', check_optional_bool, None,
+    'Verify the server\'s identity',
+    environ='SINGLESTOREDB_SSL_VERIFY_IDENTITY',
+)
+
+register_option(
+    'program_name', 'string', check_str, None,
+    'Name of the program',
+)
+
+register_option(
+    'conn_attrs', 'dict', check_dict_str_str, None,
+    'Additional connection attributes for telemetry',
+)
+
 register_option(
     'credential_type', 'str',
     functools.partial(
@@ -148,35 +181,102 @@ register_option(
     environ='SINGLESTOREDB_AUTOCOMMIT',
 )
 
+register_option(
+    'buffered', 'bool', check_bool, True,
+    'Should query results be buffered before processing?',
+    environ='SINGLESTOREDB_BUFFERED',
+)
+
+register_option(
+    'connect_timeout', 'int', check_int, 10,
+    'The timeout for connecting to the database in seconds. '
+    '(default: 10, min: 1, max: 31536000)',
+    environ='SINGLESTOREDB_CONNECT_TIMEOUT',
+)
+
+register_option(
+    'nan_as_null', 'bool', check_bool, False,
+    'Should NaN values be treated as NULLs in query parameter substitutions '
+    'including uploaded data?',
+    environ='SINGLESTOREDB_NAN_AS_NULL',
+)
+
+register_option(
+    'inf_as_null', 'bool', check_bool, False,
+    'Should Inf values be treated as NULLs in query parameter substitutions '
+    'including uploaded data?',
+    environ='SINGLESTOREDB_INF_AS_NULL',
+)
+
+register_option(
+    'track_env', 'bool', check_bool, False,
+    'Should connections track the SINGLESTOREDB_URL environment variable?',
+    environ='SINGLESTOREDB_TRACK_ENV',
+)
+
+register_option(
+    'fusion.enabled', 'bool', check_bool, False,
+    'Should Fusion SQL queries be enabled?',
+    environ='SINGLESTOREDB_FUSION_ENABLED',
+)
+
 #
 # Query results options
 #
 register_option(
-    'results.format', 'string',
+    'results.type', 'string',
     functools.partial(
         check_str,
         valid_values=[
-            'tuple', 'namedtuple',
-            'dict', 'dataframe',
+            'tuple', 'tuples', 'namedtuple', 'namedtuples',
+            'dict', 'dicts', 'structsequence', 'structsequences',
         ],
     ),
-    'tuple',
+    'tuples',
     'What form should the query results take?',
-    environ='SINGLESTOREDB_RESULTS_FORMAT',
+    environ='SINGLESTOREDB_RESULTS_TYPE',
 )
 
 register_option(
-    'results.arraysize', 'int', check_int, 100,
-    'Number of result rows to download in `fetchmany` calls',
+    'results.arraysize', 'int', check_int, 1,
+    'Number of result rows to download in `fetchmany` calls.',
     environ='SINGLESTOREDB_RESULTS_ARRAYSIZE',
 )
 
 
 #
-# Cluster manager options
+# Workspace manager options
 #
 register_option(
     'management.token', 'string', check_str, None,
     'Specifies the authentication token for the management API.',
     environ=['SINGLESTOREDB_MANAGEMENT_TOKEN'],
 )
+
+register_option(
+    'management.base_url', 'string', check_str, 'https://api.singlestore.com',
+    'Specifies the base URL for the management API.',
+    environ=['SINGLESTOREDB_MANAGEMENT_BASE_URL'],
+)
+
+register_option(
+    'management.version', 'string', check_str, 'v1',
+    'Specifies the version for the management API.',
+    environ=['SINGLESTOREDB_MANAGEMENT_VERSION'],
+)
+
+
+#
+# Debugging options
+#
+register_option(
+    'debug.queries', 'bool', check_bool, False,
+    'Print queries and parameters to stderr.',
+    environ='SINGLESTOREDB_DEBUG_QUERIES',
+)
+
+register_option(
+    'debug.connection', 'bool', check_bool, False,
+    'Print connection tracing information.',
+    environ='SINGLESTOREDB_DEBUG_CONNECTION',
+)