singlestoredb 1.16.1__py3-none-any.whl

singlestoredb/utils/xdict.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python
+#
+# Copyright SAS Institute
+#
+#  Licensed under the Apache License, Version 2.0 (the License);
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#  This file originally copied from https://github.com/sassoftware/python-swat
+#
+"""Dictionary that allows setting nested keys by period (.) delimited strings."""
+import copy
+import re
+from collections.abc import ItemsView
+from collections.abc import Iterable
+from collections.abc import KeysView
+from collections.abc import ValuesView
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Tuple
+
+
+def _is_compound_key(key: str) -> bool:
+    """
+    Check for a compound key name.
+
+    Parameters
+    ----------
+    key : string
+        The key name to check
+
+    Returns
+    -------
+    True
+        If the key is compound (i.e., contains a '.')
+    False
+        If the key is not compound
+
+    """
+    return isinstance(key, str) and '.' in key
+
+
+class xdict(Dict[str, Any]):
+    """
+    Nested dictionary that allows setting of nested keys using '.' delimited strings.
+
+    Keys with a '.' in them automatically get split into separate keys.
+    Each '.' in a key represents another level of nesting in the resulting
+    dictionary.
+
+    Parameters
+    ----------
+    *args, **kwargs : Arbitrary arguments and keyword arguments
+        Same arguments as `dict`
+
+    Returns
+    -------
+    xdict object
+
+    Examples
+    --------
+    >>> dct = xdict()
+    >>> dct['a.b.c'] = 100
+    {'a': {'b': {'c': 100}}}
+
+    """
+
+    _dir: List[str]
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super(xdict, self).__init__()
+        self.update(*args, **kwargs)
+
+    def __dir__(self) -> Iterable[str]:
+        """Return keys in the dict."""
+        if hasattr(self, '_dir') and self._dir:
+            return list(self._dir)
+        return super(xdict, self).__dir__()
+
+    def set_dir_values(self, values: List[str]) -> None:
+        """
+        Set the valid values for keys to display in tab-completion.
+
+        Parameters
+        ----------
+        values : list of strs
+            The values to display
+
+        """
+        super(xdict, self).__setattr__('_dir', values)
+
+    def set_doc(self, docstring: str) -> None:
+        """Set the docstring for the xdict."""
+        super(xdict, self).__setattr__('__doc__', docstring)
+
+    def __copy__(self) -> 'xdict':
+        """Return a copy of self."""
+        return type(self)(**self)
+
+    def __deepcopy__(self, memo: Any) -> 'xdict':
+        """Return a deep copy of self."""
+        out = type(self)()
+        for key, value in self.items():
+            if isinstance(value, (dict, list, tuple, set)):
+                value = copy.deepcopy(value)
+            out[key] = value
+        return out
+
+    @classmethod
+    def from_json(cls, jsonstr: str) -> 'xdict':
+        """
+        Create an xdict object from a JSON string.
+
+        Parameters
+        ----------
+        jsonstr : string
+           Valid JSON string that represents an object
+
+        Returns
+        -------
+        xdict object
+
+        """
+        import json
+        out = cls()
+        out.update(json.loads(jsonstr))
+        return out
+
+    def __setitem__(self, key: str, value: Any) -> Any:
+        """Set a key/value pair in an xdict object."""
+        if isinstance(value, dict) and not isinstance(value, type(self)):
+            value = type(self)(value)
+        if _is_compound_key(key):
+            return self._xset(key, value)
+        return super(xdict, self).__setitem__(key, value)
+
+    def _xset(self, key: str, value: Any) -> Any:
+        """
+        Set a key/value pair allowing nested levels in the key.
+
+        Parameters
+        ----------
+        key : any
+           Key value, if it is a string delimited by periods (.), each
+           period represents another level of nesting of xdict objects.
+        value : any
+           Data value
+
+        """
+        if isinstance(value, dict) and not isinstance(value, type(self)):
+            value = type(self)(value)
+        if _is_compound_key(key):
+            current, key = key.split('.', 1)
+            if current not in self:
+                self[current] = type(self)()
+            return self[current]._xset(key, value)
+        self[key] = value
+        return None
+
+    def setdefault(self, key: str, *default: Any) -> Any:
+        """Return keyed value, or set it to `default` if missing."""
+        if _is_compound_key(key):
+            try:
+                return self[key]
+            except KeyError:
+                if default:
+                    new_default = default[0]
+                    if isinstance(default, dict) and not isinstance(default, type(self)):
+                        new_default = type(self)(default)
+                else:
+                    new_default = None
+                self[key] = new_default
+                return new_default
+        return super(xdict, self).setdefault(key, *default)
+
+    def __contains__(self, key: object) -> bool:
+        """Does the xdict contain `key`?."""
+        if super(xdict, self).__contains__(key):
+            return True
+        return key in self.allkeys()
+
+    has_key = __contains__
+
+    def __getitem__(self, key: str) -> Any:
+        """Get value stored at `key`."""
+        if _is_compound_key(key):
+            return self._xget(key)
+        return super(xdict, self).__getitem__(key)
+
+    def _xget(self, key: str, *default: Any) -> Any:
+        """
+        Return keyed value, or `default` if missing
+
+        Parameters
+        ----------
+        key : any
+           Key to look up
+        *default : any
+           Default value to return if key is missing
+
+        Returns
+        -------
+        Any
+
+        """
+        if _is_compound_key(key):
+            current, key = key.split('.', 1)
+            try:
+                return self[current]._xget(key)
+            except KeyError:
+                if default:
+                    return default[0]
+                raise KeyError(key)
+        return self[key]
+
+    def get(self, key: str, *default: Any) -> Any:
+        """Return keyed value, or `default` if missing."""
+        if _is_compound_key(key):
+            return self._xget(key, *default)
+        return super(xdict, self).get(key, *default)
+
+    def __delitem__(self, key: str) -> Any:
+        """Deleted keyed item."""
+        if _is_compound_key(key):
+            return self._xdel(key)
+        super(xdict, self).__delitem__(key)
+
+    def _xdel(self, key: str) -> Any:
+        """
+        Delete keyed item.
+
+        Parameters
+        ----------
+        key : any
+           Key to delete.  If it is a string that is period (.) delimited,
+           each period represents another level of nesting of xdict objects.
+
+        """
+        if _is_compound_key(key):
+            current, key = key.split('.', 1)
+            try:
+                return self[current]._xdel(key)
+            except KeyError:
+                raise KeyError(key)
+        del self[key]
+
+    def pop(self, key: str, *default: Any) -> Any:
+        """Remove and return value stored at `key`."""
+        try:
+            out = self[key]
+            del self[key]
+            return out
+        except KeyError:
+            if default:
+                return default[0]
+            raise KeyError(key)
+
+    def _flatten(
+        self,
+        dct: Dict[str, Any],
+        output: Dict[str, Any],
+        prefix: str = '',
+    ) -> None:
+        """
+        Create a new dict with keys flattened to period (.) delimited keys
+
+        Parameters
+        ----------
+        dct : dict
+           The dictionary to flatten
+        output : dict
+           The resulting dictionary (used internally in recursion)
+        prefix : string
+           Key prefix built from upper levels of nesting
+
+        Returns
+        -------
+        dict
+
+        """
+        if prefix:
+            prefix = prefix + '.'
+        for key, value in dct.items():
+            if isinstance(value, dict):
+                if isinstance(key, int):
+                    intkey = '%s[%s]' % (re.sub(r'\.$', r'', prefix), key)
+                    self._flatten(value, prefix=intkey, output=output)
+                else:
+                    self._flatten(value, prefix=prefix + key, output=output)
+            else:
+                if isinstance(key, int):
+                    intkey = '%s[%s]' % (re.sub(r'\.$', r'', prefix), key)
+                    output[intkey] = value
+                else:
+                    output[prefix + key] = value
+
+    def flattened(self) -> Dict[str, Any]:
+        """Return an xdict with keys flattened to period (.) delimited strings."""
+        output: Dict[str, Any] = {}
+        self._flatten(self, output)
+        return output
+
+    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():
+            out.add(key)
+            while '.' in key:
+                key = key.rsplit('.', 1)[0]
+                out.add(key)
+                if '[' in key:
+                    out.add(re.sub(r'\[\d+\]', r'', key))
+        return list(out)
+
+    def flatkeys(self) -> List[str]:
+        """Return a list of flattened keys in the xdict."""
+        return list(self.flattened().keys())
+
+    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]]:
+        """Return tuples of flattened key/value pairs."""
+        return list(self.flattened().items())
+
+    def iterflatkeys(self) -> Iterable[str]:
+        """Return iterator of flattened keys."""
+        return iter(self.flattened().keys())
+
+    def iterflatvalues(self) -> Iterable[Any]:
+        """Return iterator of flattened values."""
+        return iter(self.flattened().values())
+
+    def iterflatitems(self) -> Iterable[Tuple[str, Any]]:
+        """Return iterator of flattened items."""
+        return iter(self.flattened().items())
+
+    def viewflatkeys(self) -> KeysView[str]:
+        """Return view of flattened keys."""
+        return self.flattened().keys()
+
+    def viewflatvalues(self) -> ValuesView[Any]:
+        """Return view of flattened values."""
+        return self.flattened().values()
+
+    def viewflatitems(self) -> ItemsView[str, Any]:
+        """Return view of flattened items."""
+        return self.flattened().items()
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        """Merge the key/value pairs into `self`."""
+        for arg in args:
+            if isinstance(arg, dict):
+                for key, value in arg.items():
+                    self._xset(key, value)
+            else:
+                for key, value in arg:
+                    self._xset(key, value)
+        for key, value in kwargs.items():
+            self._xset(key, value)
+
+    def to_json(self) -> str:
+        """
+        Convert an xdict object to a JSON string.
+
+        Returns
+        -------
+        str
+
+        """
+        import json
+        return json.dumps(self)
+
+
+class xadict(xdict):
+    """An xdict that also allows setting/getting/deleting keys as attributes."""
+
+    getdoc = None
+    trait_names = None
+
+    def _getAttributeNames(self) -> None:
+        """Block this from creating attributes."""
+        return
+
+    def __delattr__(self, key: str) -> Any:
+        """Delete the attribute stored at `key`."""
+        if key.startswith('_') and key.endswith('_'):
+            return super(xadict, self).__delattr__(key)
+        del self[key]
+
+    def __getattr__(self, key: str) -> Any:
+        """Get the attribute store at `key`."""
+        if key.startswith('_') and key.endswith('_'):
+            return super(xadict, self).__getattr__(key)  # type: ignore
+        try:
+            return self[key]
+        except KeyError:
+            dct = type(self)()
+            self[key] = dct
+            return dct
+        return None
+
+    def __getitem__(self, key: str) -> Any:
+        """Get item of an integer creates a new dict."""
+        if isinstance(key, int) and key not in self:
+            out = type(self)()
+            self[key] = out
+            return out
+        return super(xadict, self).__getitem__(key)
+
+    def __setattr__(self, key: str, value: Any) -> Any:
+        """Set the attribute stored at `key`."""
+        if key.startswith('_') and key.endswith('_'):
+            return super(xadict, self).__setattr__(key, value)
+        self[key] = value

singlestoredb/vectorstore.py

@@ -0,0 +1,192 @@
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import Optional
+
+from vectorstore import AndFilter  # noqa: F401
+from vectorstore import DeletionProtection  # noqa: F401
+from vectorstore import EqFilter  # noqa: F401
+from vectorstore import ExactMatchFilter  # noqa: F401
+from vectorstore import FilterTypedDict  # noqa: F401
+from vectorstore import GteFilter  # noqa: F401
+from vectorstore import GtFilter  # noqa: F401
+from vectorstore import IndexInterface  # noqa: F401
+from vectorstore import IndexList  # noqa: F401
+from vectorstore import IndexModel  # noqa: F401
+from vectorstore import IndexStatsTypedDict  # noqa: F401
+from vectorstore import InFilter  # noqa: F401
+from vectorstore import LteFilter  # noqa: F401
+from vectorstore import LtFilter  # noqa: F401
+from vectorstore import MatchTypedDict  # noqa: F401
+from vectorstore import Metric  # noqa: F401
+from vectorstore import NamespaceStatsTypedDict  # noqa: F401
+from vectorstore import NeFilter  # noqa: F401
+from vectorstore import NinFilter  # noqa: F401
+from vectorstore import OrFilter  # noqa: F401
+from vectorstore import SimpleFilter  # noqa: F401
+from vectorstore import Vector  # noqa: F401
+from vectorstore import VectorDictMetadataValue  # noqa: F401
+from vectorstore import VectorMetadataTypedDict  # noqa: F401
+from vectorstore import VectorTuple  # noqa: F401
+from vectorstore import VectorTupleWithMetadata  # noqa: F401
+
+
+def vector_db(
+    host: Optional[str] = None, user: Optional[str] = None,
+    password: Optional[str] = None, port: Optional[int] = None,
+    database: Optional[str] = None, driver: Optional[str] = None,
+    pure_python: Optional[bool] = None, local_infile: Optional[bool] = None,
+    charset: Optional[str] = None,
+    ssl_key: Optional[str] = None, ssl_cert: Optional[str] = None,
+    ssl_ca: Optional[str] = None, ssl_disabled: Optional[bool] = None,
+    ssl_cipher: Optional[str] = None, ssl_verify_cert: Optional[bool] = None,
+    tls_sni_servername: Optional[str] = None,
+    ssl_verify_identity: Optional[bool] = None,
+    conv: Optional[Dict[int, Callable[..., Any]]] = None,
+    credential_type: Optional[str] = None,
+    autocommit: Optional[bool] = None,
+    results_type: Optional[str] = None,
+    buffered: Optional[bool] = None,
+    results_format: Optional[str] = None,
+    program_name: Optional[str] = None,
+    conn_attrs: Optional[Dict[str, str]] = {},
+    multi_statements: Optional[bool] = None,
+    client_found_rows: Optional[bool] = None,
+    connect_timeout: Optional[int] = None,
+    nan_as_null: Optional[bool] = None,
+    inf_as_null: Optional[bool] = None,
+    encoding_errors: Optional[str] = None,
+    track_env: Optional[bool] = None,
+    enable_extended_data_types: Optional[bool] = None,
+    vector_data_format: Optional[str] = None,
+    parse_json: Optional[bool] = None,
+    pool_size: Optional[int] = 5,
+    max_overflow: Optional[int] = 10,
+    timeout: Optional[float] = 30,
+) -> Any:
+    """
+    Return a vectorstore API connection.
+    Database should be specified in the URL or as a keyword.
+
+    Parameters
+    ----------
+    host : str, optional
+        Hostname, IP address, or URL that describes the connection.
+        The scheme or protocol defines which database connector to use.
+        By default, the ``mysql`` scheme is used. To connect to the
+        HTTP API, the scheme can be set to ``http`` or ``https``. The username,
+        password, host, and port are specified as in a standard URL. The path
+        indicates the database name. The overall form of the URL is:
+        ``scheme://user:password@host:port/db_name``.  The scheme can
+        typically be left off (unless you are using the HTTP API):
+        ``user:password@host:port/db_name``.
+    user : str, optional
+        Database user name
+    password : str, optional
+        Database user password
+    port : int, optional
+        Database port. This defaults to 3306 for non-HTTP connections, 80
+        for HTTP connections, and 443 for HTTPS connections.
+    database : str, optional
+        Database name.
+    pure_python : bool, optional
+        Use the connector in pure Python mode
+    local_infile : bool, optional
+        Allow local file uploads
+    charset : str, optional
+        Character set for string values
+    ssl_key : str, optional
+        File containing SSL key
+    ssl_cert : str, optional
+        File containing SSL certificate
+    ssl_ca : str, optional
+        File containing SSL certificate authority
+    ssl_cipher : str, optional
+        Sets the SSL cipher list
+    ssl_disabled : bool, optional
+        Disable SSL usage
+    ssl_verify_cert : bool, optional
+        Verify the server's certificate. This is automatically enabled if
+        ``ssl_ca`` is also specified.
+    ssl_verify_identity : bool, optional
+        Verify the server's identity
+    conv : dict[int, Callable], optional
+        Dictionary of data conversion functions
+    credential_type : str, optional
+        Type of authentication to use: auth.PASSWORD, auth.JWT, or auth.BROWSER_SSO
+    autocommit : bool, optional
+        Enable autocommits
+    results_type : str, optional
+        The form of the query results: tuples, namedtuples, dicts,
+        numpy, polars, pandas, arrow
+    buffered : bool, optional
+        Should the entire query result be buffered in memory? This is the default
+        behavior which allows full cursor control of the result, but does consume
+        more memory.
+    results_format : str, optional
+        Deprecated. This option has been renamed to results_type.
+    program_name : str, optional
+        Name of the program
+    conn_attrs : dict, optional
+        Additional connection attributes for telemetry. Example:
+        {'program_version': "1.0.2", "_connector_name": "dbt connector"}
+    multi_statements: bool, optional
+        Should multiple statements be allowed within a single query?
+    connect_timeout : int, optional
+        The timeout for connecting to the database in seconds.
+        (default: 10, min: 1, max: 31536000)
+    nan_as_null : bool, optional
+        Should NaN values be treated as NULLs when used in parameter
+        substitutions including uploaded data?
+    inf_as_null : bool, optional
+        Should Inf values be treated as NULLs when used in parameter
+        substitutions including uploaded data?
+    encoding_errors : str, optional
+        The error handler name for value decoding errors
+    track_env : bool, optional
+        Should the connection track the SINGLESTOREDB_URL environment variable?
+    enable_extended_data_types : bool, optional
+        Should extended data types (BSON, vector) be enabled?
+    vector_data_format : str, optional
+        Format for vector types: json or binary
+    pool_size : int, optional
+        The number of connections to keep in the connection pool. Default is 5.
+    max_overflow : int, optional
+        The maximum number of connections to allow beyond the pool size.
+        Default is 10.
+    timeout : float, optional
+        The timeout for acquiring a connection from the pool in seconds.
+        Default is 30 seconds.
+
+    See Also
+    --------
+    :class:`Connection`
+
+    Returns
+    -------
+    :class:`VectorDB`
+
+    """
+    from vectorstore import VectorDB
+    return VectorDB(
+        host=host, user=user, password=password, port=port,
+        database=database, driver=driver, pure_python=pure_python,
+        local_infile=local_infile, charset=charset,
+        ssl_key=ssl_key, ssl_cert=ssl_cert, ssl_ca=ssl_ca,
+        ssl_disabled=ssl_disabled, ssl_cipher=ssl_cipher,
+        ssl_verify_cert=ssl_verify_cert,
+        tls_sni_servername=tls_sni_servername,
+        ssl_verify_identity=ssl_verify_identity, conv=conv,
+        credential_type=credential_type, autocommit=autocommit,
+        results_type=results_type, buffered=buffered,
+        results_format=results_format, program_name=program_name,
+        conn_attrs=conn_attrs, multi_statements=multi_statements,
+        client_found_rows=client_found_rows,
+        connect_timeout=connect_timeout, nan_as_null=nan_as_null,
+        inf_as_null=inf_as_null, encoding_errors=encoding_errors,
+        track_env=track_env,
+        enable_extended_data_types=enable_extended_data_types,
+        vector_data_format=vector_data_format,
+        parse_json=parse_json, pool_size=pool_size,
+        max_overflow=max_overflow, timeout=timeout,
+    )

singlestoredb/warnings.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python
+
+class PreviewFeatureWarning(UserWarning):
+    """Warning for experimental preview features."""
+    pass