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

singlestoredb/management/__init__.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-from __future__ import annotations
-
 from .cluster import manage_cluster
+from .manager import get_organization
+from .manager import get_token
+from .workspace import get_secret
 from .workspace import manage_workspaces

singlestoredb/management/billing_usage.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python
+"""SingleStoreDB Cloud Billing Usage."""
+import datetime
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+
+from .manager import Manager
+from .utils import camel_to_snake
+from .utils import vars_to_str
+
+
+class UsageItem(object):
+    """Usage statistics."""
+
+    def __init__(
+        self,
+        start_time: datetime.datetime,
+        end_time: datetime.datetime,
+        owner_id: str,
+        resource_id: str,
+        resource_name: str,
+        resource_type: str,
+        value: str,
+    ):
+        #: Starting time for the usage duration
+        self.start_time = start_time
+
+        #: Ending time for the usage duration
+        self.end_time = end_time
+
+        #: Owner ID
+        self.owner_id = owner_id
+
+        #: Resource ID
+        self.resource_id = resource_id
+
+        #: Resource name
+        self.resource_name = resource_name
+
+        #: Resource type
+        self.resource_type = resource_type
+
+        #: Usage statistic value
+        self.value = value
+
+        self._manager: Optional[Manager] = None
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return vars_to_str(self)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return str(self)
+
+    @classmethod
+    def from_dict(
+        cls,
+        obj: Dict[str, Any],
+        manager: Manager,
+    ) -> 'UsageItem':
+        """
+        Convert dictionary to a ``UsageItem`` object.
+
+        Parameters
+        ----------
+        obj : dict
+            Key-value pairs to retrieve billling usage information from
+        manager : WorkspaceManager, optional
+            The WorkspaceManager the UsageItem belongs to
+
+        Returns
+        -------
+        :class:`UsageItem`
+
+        """
+        out = cls(
+            end_time=datetime.datetime.fromisoformat(obj['endTime']),
+            start_time=datetime.datetime.fromisoformat(obj['startTime']),
+            owner_id=obj['ownerId'],
+            resource_id=obj['resourceId'],
+            resource_name=obj['resourceName'],
+            resource_type=obj['resource_type'],
+            value=obj['value'],
+        )
+        out._manager = manager
+        return out
+
+
+class BillingUsageItem(object):
+    """Billing usage item."""
+
+    def __init__(
+        self,
+        description: str,
+        metric: str,
+        usage: List[UsageItem],
+    ):
+        """Use :attr:`WorkspaceManager.billing.usage` instead."""
+        #: Description of the usage metric
+        self.description = description
+
+        #: Name of the usage metric
+        self.metric = metric
+
+        #: Usage statistics
+        self.usage = list(usage)
+
+        self._manager: Optional[Manager] = None
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return vars_to_str(self)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return str(self)
+
+    @ classmethod
+    def from_dict(
+        cls,
+        obj: Dict[str, Any],
+        manager: Manager,
+    ) -> 'BillingUsageItem':
+        """
+        Convert dictionary to a ``BillingUsageItem`` object.
+
+        Parameters
+        ----------
+        obj : dict
+            Key-value pairs to retrieve billling usage information from
+        manager : WorkspaceManager, optional
+            The WorkspaceManager the BillingUsageItem belongs to
+
+        Returns
+        -------
+        :class:`BillingUsageItem`
+
+        """
+        out = cls(
+            description=obj['description'],
+            metric=str(camel_to_snake(obj['metric'])),
+            usage=[UsageItem.from_dict(x, manager) for x in obj['Usage']],
+        )
+        out._manager = manager
+        return out

singlestoredb/management/cluster.py

@@ -1,10 +1,7 @@
 #!/usr/bin/env python
 """SingleStoreDB Cluster Management."""
-from __future__ import annotations
-
 import datetime
 import warnings
-from collections.abc import Sequence
 from typing import Any
 from typing import Dict
 from typing import List
@@ -15,6 +12,7 @@ from .. import connection
 from ..exceptions import ManagementError
 from .manager import Manager
 from .region import Region
+from .utils import NamedList
 from .utils import to_datetime
 from .utils import vars_to_str
 
@@ -41,7 +39,7 @@ class Cluster(object):
         units: float, state: str, version: str,
         created_at: Union[str, datetime.datetime],
         expires_at: Optional[Union[str, datetime.datetime]] = None,
-        firewall_ranges: Optional[Sequence[str]] = None,
+        firewall_ranges: Optional[List[str]] = None,
         terminated_at: Optional[Union[str, datetime.datetime]] = None,
         endpoint: Optional[str] = None,
     ):
@@ -94,7 +92,7 @@ class Cluster(object):
         return str(self)
 
     @classmethod
-    def from_dict(cls, obj: Dict[str, Any], manager: 'ClusterManager') -> Cluster:
+    def from_dict(cls, obj: Dict[str, Any], manager: 'ClusterManager') -> 'Cluster':
         """
         Construct a Cluster from a dictionary of values.
 
@@ -123,7 +121,7 @@ class Cluster(object):
         out._manager = manager
         return out
 
-    def refresh(self) -> Cluster:
+    def refresh(self) -> 'Cluster':
         """Update the object to the current state."""
         if self._manager is None:
             raise ManagementError(
@@ -138,7 +136,7 @@ class Cluster(object):
         self, name: Optional[str] = None,
         admin_password: Optional[str] = None,
         expires_at: Optional[str] = None,
-        size: Optional[str] = None, firewall_ranges: Optional[Sequence[str]] = None,
+        size: Optional[str] = None, firewall_ranges: Optional[List[str]] = None,
     ) -> None:
         """
         Update the cluster definition.
@@ -340,20 +338,20 @@ class ClusterManager(Manager):
     obj_type = 'cluster'
 
     @property
-    def clusters(self) -> List[Cluster]:
+    def clusters(self) -> NamedList[Cluster]:
         """Return a list of available clusters."""
         res = self._get('clusters')
-        return [Cluster.from_dict(item, self) for item in res.json()]
+        return NamedList([Cluster.from_dict(item, self) for item in res.json()])
 
     @property
-    def regions(self) -> List[Region]:
+    def regions(self) -> NamedList[Region]:
         """Return a list of available regions."""
         res = self._get('regions')
-        return [Region.from_dict(item, self) for item in res.json()]
+        return NamedList([Region.from_dict(item, self) for item in res.json()])
 
     def create_cluster(
         self, name: str, region: Union[str, Region], admin_password: str,
-        firewall_ranges: Sequence[str], expires_at: Optional[str] = None,
+        firewall_ranges: List[str], expires_at: Optional[str] = None,
         size: Optional[str] = None, plan: Optional[str] = None,
         wait_on_active: bool = False, wait_timeout: int = 600,
         wait_interval: int = 20,
@@ -429,6 +427,8 @@ def manage_cluster(
     access_token: Optional[str] = None,
     version: str = ClusterManager.default_version,
     base_url: str = ClusterManager.default_base_url,
+    *,
+    organization_id: Optional[str] = None,
 ) -> ClusterManager:
     """
     Retrieve a SingleStoreDB cluster manager.
@@ -441,6 +441,8 @@ def manage_cluster(
         Version of the API to use
     base_url : str, optional
         Base URL of the cluster management API
+    organization_id: str, optional
+        ID of organization, if using a JWT for authentication
 
     Returns
     -------
@@ -449,7 +451,10 @@ def manage_cluster(
     """
     warnings.warn(
         'The cluster management API is deprecated; '
-        'use manage_workspace instead.',
+        'use manage_workspaces instead.',
         category=DeprecationWarning,
     )
-    return ClusterManager(access_token=access_token, base_url=base_url, version=version)
+    return ClusterManager(
+        access_token=access_token, base_url=base_url,
+        version=version, organization_id=organization_id,
+    )

singlestoredb/management/manager.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 """SingleStoreDB Base Manager."""
-from __future__ import annotations
-
+import os
+import sys
 import time
 from typing import Any
 from typing import Dict
@@ -10,44 +10,73 @@ from typing import Optional
 from typing import Union
 from urllib.parse import urljoin
 
+import jwt
 import requests
 
 from .. import config
 from ..exceptions import ManagementError
+from .utils import get_organization
+from .utils import get_token
+
+
+def set_organization(kwargs: Dict[str, Any]) -> None:
+    """Set the organization ID in the dictionary."""
+    if kwargs.get('params', {}).get('organizationID', None):
+        return
+
+    org = get_organization()
+    if org:
+        if 'params' not in kwargs:
+            kwargs['params'] = {}
+        kwargs['params']['organizationID'] = org
+
+
+def is_jwt(token: str) -> bool:
+    """Is the given token a JWT?"""
+    try:
+        jwt.decode(token, options={'verify_signature': False})
+        return True
+    except jwt.DecodeError:
+        return False
 
 
 class Manager(object):
     """SingleStoreDB manager base class."""
 
     #: Management API version if none is specified.
-    default_version = 'v1'
+    default_version = config.get_option('management.version')
 
     #: Base URL if none is specified.
-    default_base_url = 'https://api.singlestore.com'
+    default_base_url = config.get_option('management.base_url')
 
     #: Object type
     obj_type = ''
 
     def __init__(
         self, access_token: Optional[str] = None, version: Optional[str] = None,
-        base_url: Optional[str] = None,
+        base_url: Optional[str] = None, *, organization_id: Optional[str] = None,
     ):
-        access_token = (
-            access_token or
-            config.get_option('management.token')
+        from .. import __version__ as client_version
+        new_access_token = (
+            access_token or get_token()
         )
-        if not access_token:
+        if not new_access_token:
             raise ManagementError(msg='No management token was configured.')
+        self._is_jwt = not access_token and new_access_token and is_jwt(new_access_token)
         self._sess = requests.Session()
         self._sess.headers.update({
-            'Authorization': f'Bearer {access_token}',
+            'Authorization': f'Bearer {new_access_token}',
             'Content-Type': 'application/json',
             'Accept': 'application/json',
+            'User-Agent': f'SingleStoreDB-Python/{client_version}',
         })
         self._base_url = urljoin(
             base_url or type(self).default_base_url,
             version or type(self).default_version,
         ) + '/'
+        self._params: Dict[str, str] = {}
+        if organization_id:
+            self._params['organizationID'] = organization_id
 
     def _check(
         self, res: requests.Response, url: str, params: Dict[str, Any],
@@ -65,6 +94,8 @@ class Manager(object):
         requests.Response
 
         """
+        if config.get_option('debug.queries'):
+            print(os.path.join(self._base_url, url), params, file=sys.stderr)
         if res.status_code >= 400:
             txt = res.text.strip()
             msg = f'{txt}: /{url}'
@@ -72,12 +103,27 @@ class Manager(object):
                 new_params = params.copy()
                 if 'json' in new_params:
                     for k, v in new_params['json'].items():
-                        if 'password' in k.lower():
+                        if 'password' in k.lower() and v:
                             new_params['json'][k] = '*' * len(v)
                 msg += ': {}'.format(str(new_params))
-            raise ManagementError(errno=res.status_code, msg=msg)
+            raise ManagementError(errno=res.status_code, msg=msg, response=txt)
         return res
 
+    def _doit(
+        self,
+        method: str,
+        path: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> requests.Response:
+        """Perform HTTP request."""
+        # Refresh the JWT as needed
+        if self._is_jwt:
+            self._sess.headers.update({'Authorization': f'Bearer {get_token()}'})
+        return getattr(self._sess, method.lower())(
+            urljoin(self._base_url, path), *args, **kwargs,
+        )
+
     def _get(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
         """
         Invoke a GET request.
@@ -96,13 +142,10 @@ class Manager(object):
         requests.Response
 
         """
-        return self._check(
-            self._sess.get(
-                urljoin(self._base_url, path),
-                *args, **kwargs,
-            ),
-            path, kwargs,
-        )
+        if self._params:
+            kwargs['params'] = self._params
+        set_organization(kwargs)
+        return self._check(self._doit('get', path, *args, **kwargs), path, kwargs)
 
     def _post(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
         """
@@ -122,13 +165,33 @@ class Manager(object):
         requests.Response
 
         """
-        return self._check(
-            self._sess.post(
-                urljoin(self._base_url, path),
-                *args, **kwargs,
-            ),
-            path, kwargs,
-        )
+        if self._params:
+            kwargs['params'] = self._params
+        set_organization(kwargs)
+        return self._check(self._doit('post', path, *args, **kwargs), path, kwargs)
+
+    def _put(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
+        """
+        Invoke a PUT request.
+
+        Parameters
+        ----------
+        path : str
+            Path of the resource
+        *args : positional arguments, optional
+            Arguments to add to the POST request
+        **kwargs : keyword arguments, optional
+            Keyword arguments to add to the POST request
+
+        Returns
+        -------
+        requests.Response
+
+        """
+        if self._params:
+            kwargs['params'] = self._params
+        set_organization(kwargs)
+        return self._check(self._doit('put', path, *args, **kwargs), path, kwargs)
 
     def _delete(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
         """
@@ -148,13 +211,10 @@ class Manager(object):
         requests.Response
 
         """
-        return self._check(
-            self._sess.delete(
-                urljoin(self._base_url, path),
-                *args, **kwargs,
-            ),
-            path, kwargs,
-        )
+        if self._params:
+            kwargs['params'] = self._params
+        set_organization(kwargs)
+        return self._check(self._doit('delete', path, *args, **kwargs), path, kwargs)
 
     def _patch(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
         """
@@ -174,13 +234,10 @@ class Manager(object):
         requests.Response
 
         """
-        return self._check(
-            self._sess.patch(
-                urljoin(self._base_url, path),
-                *args, **kwargs,
-            ),
-            path, kwargs,
-        )
+        if self._params:
+            kwargs['params'] = self._params
+        set_organization(kwargs)
+        return self._check(self._doit('patch', path, *args, **kwargs), path, kwargs)
 
     def _wait_on_state(
         self,
@@ -217,12 +274,14 @@ class Manager(object):
             x.lower().strip()
             for x in (isinstance(state, str) and [state] or state)
         ]
+
         if getattr(out, 'state', None) is None:
             raise ManagementError(
                 msg='{} object does not have a `state` attribute'.format(
                     type(out).__name__,
                 ),
             )
+
         while True:
             if getattr(out, 'state').lower() in states:
                 break
@@ -234,4 +293,5 @@ class Manager(object):
             time.sleep(interval)
             timeout -= interval
             out = getattr(self, f'get_{self.obj_type}')(out.id)
+
         return out

singlestoredb/management/organization.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python
+"""SingleStoreDB Cloud Organization."""
+import datetime
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Union
+
+from ..exceptions import ManagementError
+from .manager import Manager
+from .utils import vars_to_str
+
+
+def listify(x: Union[str, List[str]]) -> List[str]:
+    if isinstance(x, list):
+        return x
+    return [x]
+
+
+def stringify(x: Union[str, List[str]]) -> str:
+    if isinstance(x, list):
+        return x[0]
+    return x
+
+
+class Secret(object):
+    """
+    SingleStoreDB secrets definition.
+
+    This object is not directly instantiated. It is used in results
+    of API calls on the :class:`Organization`. See :meth:`Organization.get_secret`.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        value: str,
+        created_by: str,
+        created_at: Union[str, datetime.datetime],
+        last_updated_by: str,
+        last_updated_at: Union[str, datetime.datetime],
+        deleted_by: Optional[str] = None,
+        deleted_at: Optional[Union[str, datetime.datetime]] = None,
+    ):
+        # UUID of the secret
+        self.id = id
+
+        # Name of the secret
+        self.name = name
+
+        # Value of the secret
+        self.value = value
+
+        # User who created the secret
+        self.created_by = created_by
+
+        # Time when the secret was created
+        self.created_at = created_at
+
+        # UUID of the user who last updated the secret
+        self.last_updated_by = last_updated_by
+
+        # Time when the secret was last updated
+        self.last_updated_at = last_updated_at
+
+        # UUID of the user who deleted the secret
+        self.deleted_by = deleted_by
+
+        # Time when the secret was deleted
+        self.deleted_at = deleted_at
+
+    @classmethod
+    def from_dict(cls, obj: Dict[str, str]) -> 'Secret':
+        """
+        Construct a Secret from a dictionary of values.
+
+        Parameters
+        ----------
+        obj : dict
+            Dictionary of values
+
+        Returns
+        -------
+        :class:`Secret`
+
+        """
+        out = cls(
+            id=obj['secretID'],
+            name=obj['name'],
+            value=obj['value'],
+            created_by=obj['createdBy'],
+            created_at=obj['createdAt'],
+            last_updated_by=obj['lastUpdatedBy'],
+            last_updated_at=obj['lastUpdatedAt'],
+            deleted_by=obj.get('deletedBy'),
+            deleted_at=obj.get('deletedAt'),
+        )
+
+        return out
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return vars_to_str(self)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return str(self)
+
+
+class Organization(object):
+    """
+    Organization in SingleStoreDB Cloud portal.
+
+    This object is not directly instantiated. It is used in results
+    of ``WorkspaceManager`` API calls.
+
+    See Also
+    --------
+    :attr:`WorkspaceManager.organization`
+
+    """
+
+    def __init__(self, id: str, name: str, firewall_ranges: List[str]):
+        """Use :attr:`WorkspaceManager.organization` instead."""
+        #: Unique ID of the organization
+        self.id = id
+
+        #: Name of the organization
+        self.name = name
+
+        #: Firewall ranges of the organization
+        self.firewall_ranges = list(firewall_ranges)
+
+        self._manager: Optional[Manager] = None
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return vars_to_str(self)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return str(self)
+
+    def get_secret(self, name: str) -> Secret:
+        if self._manager is None:
+            raise ManagementError(msg='Organization not initialized')
+
+        res = self._manager._get('secrets', params=dict(name=name))
+
+        secrets = [Secret.from_dict(item) for item in res.json()['secrets']]
+
+        if len(secrets) == 0:
+            raise ManagementError(msg=f'Secret {name} not found')
+
+        if len(secrets) > 1:
+            raise ManagementError(msg=f'Multiple secrets found for {name}')
+
+        return secrets[0]
+
+    @classmethod
+    def from_dict(
+        cls,
+        obj: Dict[str, Union[str, List[str]]],
+        manager: Manager,
+    ) -> 'Organization':
+        """
+        Convert dictionary to an ``Organization`` object.
+
+        Parameters
+        ----------
+        obj : dict
+            Key-value pairs to retrieve organization information from
+        manager : WorkspaceManager, optional
+            The WorkspaceManager the Organization belongs to
+
+        Returns
+        -------
+        :class:`Organization`
+
+        """
+        out = cls(
+            id=stringify(obj['orgID']),
+            name=stringify(obj.get('name', '<unknown>')),
+            firewall_ranges=listify(obj.get('firewallRanges', [])),
+        )
+        out._manager = manager
+        return out