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

singlestoredb/tests/utils.py

@@ -1,8 +1,6 @@
 #!/usr/bin/env python
 # type: ignore
 """Utilities for testing."""
-from __future__ import annotations
-
 import os
 import uuid
 from typing import Any
@@ -88,11 +86,12 @@ def load_sql(sql_file: str) -> str:
                         if cmd:
                             cmd += ';'
                             cur.execute(cmd)
-                else:
+
+                elif not conn.driver.startswith('http'):
                     cur.execute(f'USE {dbname};')
 
                 # Start HTTP server as needed.
-                if http_port:
+                if http_port and not conn.driver.startswith('http'):
                     cur.execute(f'SET GLOBAL HTTP_PROXY_PORT={http_port};')
                     cur.execute('SET GLOBAL HTTP_API=ON;')
                     cur.execute('RESTART PROXY;')

singlestoredb/types.py

@@ -1,13 +1,12 @@
 #!/usr/bin/env python
 """SingleStoreDB data type utilities."""
-from __future__ import annotations
-
 import datetime
 import decimal
 import time
 from typing import Dict
 from typing import List
 from typing import Set
+from typing import Union
 
 
 Date = datetime.date
@@ -78,8 +77,8 @@ class DBAPIType(object):
 
     """
 
-    def __init__(self, *values: int | str | type | DBAPIType):
-        self.values: Set[int | str | type] = set()
+    def __init__(self, *values: Union[int, str, type, 'DBAPIType']):
+        self.values: Set[Union[int, str, type]] = set()
         name: str = ''
         code: int = -1
         for item in values:
@@ -135,7 +134,7 @@ class DBAPIType(object):
         bool
 
         """
-        return not(self.__eq__(other))
+        return not (self.__eq__(other))
 
     def __str__(self) -> str:
         """Return string representation."""

singlestoredb/utils/config.py

@@ -24,15 +24,17 @@ reset_option(...).  The describe_option(...) function can be used to display
 a description of one or more options.
 
 """
-from __future__ import annotations
-
 import contextlib
 import os
 import re
 from typing import Any
 from typing import Callable
+from typing import Dict
 from typing import Iterator
+from typing import List
+from typing import Mapping
 from typing import Optional
+from typing import Tuple
 from typing import Union
 from urllib.parse import urlparse
 
@@ -45,7 +47,7 @@ _config = xdict()
 items_types = (list, tuple, set)
 
 
-def _getenv(names: Union[str, list[str]], *args: Any) -> str:
+def _getenv(names: Union[str, List[str]], *args: Any) -> str:
     """
     Check for multiple environment variable values.
 
@@ -79,7 +81,7 @@ def _getenv(names: Union[str, list[str]], *args: Any) -> str:
     raise KeyError(names[0])
 
 
-def _setenv(names: Union[str, list[str]], value: Any) -> None:
+def _setenv(names: Union[str, List[str]], value: Any) -> None:
     """
     Set environment variable.
 
@@ -109,7 +111,7 @@ def _setenv(names: Union[str, list[str]], value: Any) -> None:
             os.environ[name] = value
 
 
-def _delenv(names: Union[str, list[str]]) -> None:
+def _delenv(names: Union[str, List[str]]) -> None:
     """Delete given environment variables."""
     if not isinstance(names, items_types):
         names = [names]
@@ -118,7 +120,7 @@ def _delenv(names: Union[str, list[str]]) -> None:
         os.environ.pop(name.replace('_', ''), None)
 
 
-def iteroptions(*args: Any, **kwargs: Any) -> Iterator[tuple[str, Any]]:
+def iteroptions(*args: Any, **kwargs: Any) -> Iterator[Tuple[str, Any]]:
     """
     Iterate through name / value pairs of options
 
@@ -264,7 +266,7 @@ def get_option(key: str) -> Any:
     return opt.get()
 
 
-def get_suboptions(key: str) -> dict[str, Any]:
+def get_suboptions(key: str) -> Dict[str, Any]:
     """
     Get the dictionary of options at the level `key`.
 
@@ -561,12 +563,34 @@ def check_bool(value: Union[bool, int]) -> bool:
     raise ValueError('%s is not a recognized bool value')
 
 
+def check_optional_bool(value: Optional[Union[bool, int]]) -> Optional[bool]:
+    """
+    Validate an optional bool value.
+
+    Parameters
+    ----------
+    value : int or bool or None
+        The value to validate.  If specified as an integer, it must
+        be either 0 for False or 1 for True.
+
+    Returns
+    -------
+    bool
+        The validated bool
+
+    """
+    if value is None:
+        return None
+
+    return check_bool(value)
+
+
 def check_str(
     value: Any,
     pattern: Optional[str] = None,
     max_length: Optional[int] = None,
     min_length: Optional[int] = None,
-    valid_values: Optional[list[str]] = None,
+    valid_values: Optional[List[str]] = None,
 ) -> Optional[str]:
     """
     Validate a string value.
@@ -622,12 +646,47 @@ def check_str(
     return out
 
 
+def check_dict_str_str(
+    value: Any,
+) -> Optional[Dict[str, str]]:
+    """
+    Validate a string value.
+
+    Parameters
+    ----------
+    value : dict
+        The value to validate. Keys and values must be strings.
+
+    Returns
+    -------
+    dict
+        The validated dict value
+    """
+    if value is None:
+        return None
+
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            'value {} must be of type dict'.format(value),
+        )
+
+    out = {}
+    for k, v in value.items():
+        if not isinstance(k, str) or not isinstance(v, str):
+            raise ValueError(
+                'keys and values in {} must be strings'.format(value),
+            )
+        out[k] = v
+
+    return out
+
+
 def check_url(
     value: str,
     pattern: Optional[str] = None,
     max_length: Optional[int] = None,
     min_length: Optional[int] = None,
-    valid_values: Optional[list[str]] = None,
+    valid_values: Optional[List[str]] = None,
 ) -> Optional[str]:
     """
     Validate a URL value.
@@ -696,7 +755,7 @@ class Option(object):
         validator: Callable[[str], Any],
         default: Any,
         doc: str,
-        environ: Optional[Union[str, list[str]]] = None,
+        environ: Optional[Union[str, List[str]]] = None,
     ):
         self._name = name
         self._typedesc = typedesc
@@ -776,7 +835,7 @@ def register_option(
     validator: Callable[[Any], Any],
     default: Any,
     doc: str,
-    environ: Optional[Union[str, list[str]]] = None,
+    environ: Optional[Union[str, List[str]]] = None,
 ) -> None:
     """
     Register a new option.
@@ -819,7 +878,7 @@ class AttrOption(object):
     def __init__(self, name: str):
         object.__setattr__(self, '_name', name)
 
-    def __dir__(self) -> list[str]:
+    def __dir__(self) -> List[str]:
         """Return list of flattened keys."""
         if self._name in _config:
             return _config[self._name].flatkeys()

singlestoredb/utils/convert_rows.py

@@ -1,7 +1,5 @@
 #!/usr/bin/env python
 """Data value conversion utilities."""
-from __future__ import annotations
-
 from typing import Any
 from typing import List
 from typing import Optional

singlestoredb/utils/debug.py

@@ -0,0 +1,13 @@
+import sys
+from typing import Any
+
+from ..config import get_option
+
+
+def log_query(query: str, args: Any = None) -> None:
+    """Log the query and parameters."""
+    if get_option('debug.queries'):
+        if args is None:
+            print('[QUERY]', query, file=sys.stderr)
+        else:
+            print('[QUERY]', query, args, file=sys.stderr)

singlestoredb/utils/mogrify.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+from typing import Any
+from typing import Dict
+from typing import Optional
+from typing import Sequence
+from typing import Union
+
+from ..mysql import converters
+from ..mysql.constants import SERVER_STATUS
+
+
+Encoders = converters.Encoders
+
+
+def escape(
+    obj: Any,
+    charset: str = 'utf8',
+    mapping: Optional[Encoders] = None,
+    server_status: int = 0,
+    binary_prefix: bool = False,
+) -> str:
+    """
+    Escape whatever value is passed.
+
+    Non-standard, for internal use; do not use this in your applications.
+
+    """
+    dtype = type(obj)
+    if dtype is str or isinstance(obj, str):
+        return "'{}'".format(escape_string(obj, server_status=server_status))
+    if dtype is bytes or dtype is bytearray or isinstance(obj, (bytes, bytearray)):
+        return _quote_bytes(
+            obj,
+            server_status=server_status,
+            binary_prefix=binary_prefix,
+        )
+    if mapping is None:
+        mapping = converters.encoders
+    return converters.escape_item(obj, charset, mapping=mapping)
+
+
+def literal(
+    obj: Any,
+    charset: str = 'utf8',
+    encoders: Optional[Encoders] = None,
+    server_status: int = 0,
+    binary_prefix: bool = False,
+) -> str:
+    """
+    Alias for escape().
+
+    Non-standard, for internal use; do not use this in your applications.
+
+    """
+    return escape(
+        obj, charset=charset, mapping=encoders,
+        server_status=server_status, binary_prefix=binary_prefix,
+    )
+
+
+def escape_string(
+    s: str,
+    server_status: int = 0,
+) -> str:
+    """Escape a string value."""
+    if server_status & SERVER_STATUS.SERVER_STATUS_NO_BACKSLASH_ESCAPES:
+        return s.replace("'", "''")
+    return converters.escape_string(s)
+
+
+def _quote_bytes(
+    s: bytes,
+    server_status: int = 0,
+    binary_prefix: bool = False,
+) -> str:
+    if server_status & SERVER_STATUS.SERVER_STATUS_NO_BACKSLASH_ESCAPES:
+        if binary_prefix:
+            return "_binary X'{}'".format(s.hex())
+        return "X'{}'".format(s.hex())
+    return converters.escape_bytes(s)
+
+
+def _escape_args(
+    args: Union[Sequence[Any], Dict[str, Any], None],
+    charset: str = 'utf8',
+    encoders: Optional[Encoders] = None,
+    server_status: int = 0,
+    binary_prefix: bool = False,
+) -> Any:
+    if encoders is None:
+        encoders = converters.encoders
+
+    if isinstance(args, (tuple, list)):
+        return tuple(
+            literal(
+                arg, charset=charset, encoders=encoders,
+                server_status=server_status,
+                binary_prefix=binary_prefix,
+            ) for arg in args
+        )
+
+    elif isinstance(args, dict):
+        return {
+            key: literal(
+                val, charset=charset, encoders=encoders,
+                server_status=server_status,
+                binary_prefix=binary_prefix,
+            ) for (key, val) in args.items()
+        }
+
+    # If it's not a dictionary let's try escaping it anyways.
+    # Worst case it will throw a Value error
+    return escape(
+        args, charset=charset, mapping=encoders,
+        server_status=server_status, binary_prefix=binary_prefix,
+    )
+
+
+def mogrify(
+    query: Union[str, bytes],
+    args: Union[Sequence[Any], Dict[str, Any], None] = None,
+    charset: str = 'utf8',
+    encoders: Optional[Encoders] = None,
+    server_status: int = 0,
+    binary_prefix: bool = False,
+) -> Union[str, bytes]:
+    """
+    Returns the exact string sent to the database by calling the execute() method.
+
+    This method follows the extension to the DB API 2.0 followed by Psycopg.
+
+    Parameters
+    ----------
+    query : str
+        Query to mogrify.
+    args : Sequence[Any] or Dict[str, Any] or Any, optional
+        Parameters used with query. (optional)
+
+    Returns
+    -------
+    str : The query with argument binding applied.
+
+    """
+    if args:
+        query = query % _escape_args(
+            args, charset=charset,
+            encoders=encoders,
+            server_status=server_status,
+            binary_prefix=binary_prefix,
+        )
+    return query

singlestoredb/utils/results.py

@@ -1,7 +1,5 @@
 #!/usr/bin/env python
 """SingleStoreDB package utilities."""
-from __future__ import annotations
-
 import collections
 import warnings
 from typing import Any
@@ -30,7 +28,7 @@ class Description(NamedTuple):
     """Column definition."""
 
     name: str
-    type_code: str
+    type_code: int
     display_size: Optional[int]
     internal_size: Optional[int]
     precision: Optional[int]
@@ -192,8 +190,11 @@ _converters: Dict[
     ],
 ] = {
     'tuple': results_to_tuple,
+    'tuples': results_to_tuple,
     'namedtuple': results_to_namedtuple,
+    'namedtuples': results_to_namedtuple,
     'dict': results_to_dict,
+    'dicts': results_to_dict,
     'dataframe': results_to_dataframe,
 }
 

singlestoredb/utils/xdict.py

@@ -17,8 +17,6 @@
 #  This file originally copied from https://github.com/sassoftware/python-swat
 #
 """Dictionary that allows setting nested keys by period (.) delimited strings."""
-from __future__ import annotations
-
 import copy
 import re
 from typing import Any
@@ -26,6 +24,8 @@ from typing import Dict
 from typing import ItemsView
 from typing import Iterable
 from typing import KeysView
+from typing import List
+from typing import Tuple
 from typing import ValuesView
 
 
@@ -74,7 +74,7 @@ class xdict(Dict[str, Any]):
 
     """
 
-    _dir: list[str]
+    _dir: List[str]
 
     def __init__(self, *args: Any, **kwargs: Any):
         super(xdict, self).__init__()
@@ -86,7 +86,7 @@ class xdict(Dict[str, Any]):
             return list(self._dir)
         return super(xdict, self).__dir__()
 
-    def set_dir_values(self, values: list[str]) -> None:
+    def set_dir_values(self, values: List[str]) -> None:
         """
         Set the valid values for keys to display in tab-completion.
 
@@ -102,11 +102,11 @@ class xdict(Dict[str, Any]):
         """Set the docstring for the xdict."""
         super(xdict, self).__setattr__('__doc__', docstring)
 
-    def __copy__(self) -> xdict:
+    def __copy__(self) -> 'xdict':
         """Return a copy of self."""
         return type(self)(**self)
 
-    def __deepcopy__(self, memo: Any) -> xdict:
+    def __deepcopy__(self, memo: Any) -> 'xdict':
         """Return a deep copy of self."""
         out = type(self)()
         for key, value in self.items():
@@ -116,7 +116,7 @@ class xdict(Dict[str, Any]):
         return out
 
     @classmethod
-    def from_json(cls, jsonstr: str) -> xdict:
+    def from_json(cls, jsonstr: str) -> 'xdict':
         """
         Create an xdict object from a JSON string.
 
@@ -309,7 +309,7 @@ class xdict(Dict[str, Any]):
         self._flatten(self, output)
         return output
 
-    def allkeys(self) -> list[str]:
+    def allkeys(self) -> List[str]:
         """Return a list of all possible keys (even sub-keys) in the xdict."""
         out = set()
         for key in self.flatkeys():
@@ -321,15 +321,15 @@ class xdict(Dict[str, Any]):
                     out.add(re.sub(r'\[\d+\]', r'', key))
         return list(out)
 
-    def flatkeys(self) -> list[str]:
+    def flatkeys(self) -> List[str]:
         """Return a list of flattened keys in the xdict."""
         return list(self.flattened().keys())
 
-    def flatvalues(self) -> list[Any]:
+    def flatvalues(self) -> List[Any]:
         """Return a list of flattened values in the xdict."""
         return list(self.flattened().values())
 
-    def flatitems(self) -> list[tuple[str, Any]]:
+    def flatitems(self) -> List[Tuple[str, Any]]:
         """Return tuples of flattened key/value pairs."""
         return list(self.flattened().items())
 
@@ -341,7 +341,7 @@ class xdict(Dict[str, Any]):
         """Return iterator of flattened values."""
         return iter(self.flattened().values())
 
-    def iterflatitems(self) -> Iterable[tuple[str, Any]]:
+    def iterflatitems(self) -> Iterable[Tuple[str, Any]]:
         """Return iterator of flattened items."""
         return iter(self.flattened().items())
 

singlestoredb-1.0.3.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.1
+Name: singlestoredb
+Version: 1.0.3
+Summary: Interface to the SingleStoreDB database and workspace management APIs
+Home-page: https://github.com/singlestore-labs/singlestoredb-python
+Author: SingleStore
+Author-email: support@singlestore.com
+License: Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyJWT
+Requires-Dist: build
+Requires-Dist: parsimonious
+Requires-Dist: requests
+Requires-Dist: setuptools
+Requires-Dist: sqlparams
+Requires-Dist: wheel
+Provides-Extra: dataframe
+Requires-Dist: ibis-singlestoredb ; extra == 'dataframe'
+Provides-Extra: dbt
+Requires-Dist: dbt-singlestore ; extra == 'dbt'
+Provides-Extra: ed22519
+Requires-Dist: PyNaCl >=1.4.0 ; extra == 'ed22519'
+Provides-Extra: gssapi
+Requires-Dist: gssapi ; extra == 'gssapi'
+Provides-Extra: ibis
+Requires-Dist: ibis-singlestoredb ; extra == 'ibis'
+Provides-Extra: kerberos
+Requires-Dist: gssapi ; extra == 'kerberos'
+Provides-Extra: pytest
+Requires-Dist: pytest ; extra == 'pytest'
+Provides-Extra: rsa
+Requires-Dist: cryptography ; extra == 'rsa'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy-singlestoredb >=1.0.0 ; extra == 'sqlalchemy'
+
+# <img src="https://github.com/singlestore-labs/singlestoredb-python/blob/main/resources/singlestore-logo.png" height="60" valign="middle"/> SingleStoreDB Python SDK
+
+This project contains a [DB-API 2.0](https://www.python.org/dev/peps/pep-0249/)
+compatible Python interface to the SingleStore database and workspace management API.
+
+## Install
+
+This package can be install from PyPI using `pip`:
+```
+pip install singlestoredb
+```
+
+## Documentation
+
+https://singlestore-labs.github.io/singlestoredb-python
+
+## Usage
+
+Connections to the SingleStore database are made using the DB-API parameters
+`host`, `port`, `user`, `password`, etc, but they may also be done using
+URLs that specify these parameters as well (much like the
+[SQLAlchemy](https://www.sqlalchemy.org) package).
+```
+import singlestoredb as s2
+
+# Connect using the default connector
+conn = s2.connect('user:password@host:3306/db_name')
+
+# Create a cursor
+cur = conn.cursor()
+
+# Execute SQL
+cur.execute('select * from foo')
+
+# Fetch the results
+print(cur.description)
+for item in cur:
+    print(item)
+
+# Close the connection
+conn.close()
+```
+
+Connecting to the HTTP API is done as follows:
+```
+# Use the HTTP API connector
+conn = s2.connect('https://user:password@host:8080/db_name')
+```
+
+## Performance
+
+While this package is based on [PyMySQL](https://github.com/PyMySQL/PyMySQL)
+which is a pure Python-based MySQL connector, it adds various performance
+enhancements that make it faster than most other connectors. The performance
+improvements come from changes to the data conversion functions, cursor implementations,
+and a C extension that is highly optimized to improve row data reading.
+
+The package can be used both in a pure Python mode and as well as a C accelerated
+mode. Generally speaking, the C accelerated version of the client can read
+data 10X faster than PyMySQL, 2X faster than MySQLdb, and 1.5X faster than
+mysql.connector. All of this is done without having to install any 3rd party
+MySQL libraries!
+
+Benchmarking was done with a table of 3,533,286 rows each containing a datetime,
+a float, and eight character columns. The data is the same data set used in
+[this article](https://www.singlestore.com/blog/how-to-get-started-with-singlestore/).
+The client and server were running on the same machine and queries were made
+using `fetchone`, `fetchall`, `fetchmany(1000)`, and an iterator over the cursor
+object (e.g., `iter(cur)`). The results are shown below.
+
+### Buffered
+
+|                         | PyMySQL | MySQLdb | mysql.connector | SingleStore (pure Python) | SingleStore |
+|-------------------------|---------|---------|-----------------|---------------------------|-------------|
+| fetchall                |   37.0s |    8.7s |            5.6s |                     29.0s |        3.7s |
+| fetchmany(1000)         |   37.4s |    9.2s |            6.2s |                     29.6s |        3.6s |
+| fetchone                |   38.2s |   10.1s |            10.2s |                     30.9s |        4.8s |
+| iter(cur)               |   38.3s |    9.1s |            10.2s |                     30.4s |        4.4s |
+
+### Unbuffered
+
+|                         | PyMySQL | MySQLdb | mysql.connector | SingleStore (pure Python) | SingleStore |
+|-------------------------|---------|---------|-----------------|---------------------------|-------------|
+| fetchall                |   39.0s |    6.5s |            5.5s |                     30.3s |        5.5s |
+| fetchmany(1000)         |   39.4s |    7.0s |            6.0s |                     30.4s |        4.1s |
+| fetchone                |   34.5s |    8.9s |           10.1s |                     30.8s |        6.6s |
+| iter(cur)               |   39.0s |    9.0s |           10.2s |                     31.4s |        6.0s |
+
+
+## License
+
+This library is licensed under the [Apache 2.0 License](https://raw.githubusercontent.com/singlestore-labs/singlestoredb-python/main/LICENSE?token=GHSAT0AAAAAABMGV6QPNR6N23BVICDYK5LAYTVK5EA).
+
+## Resources
+
+* [SingleStore](https://singlestore.com)
+* [Python](https://python.org)