meerschaum 2.9.5__py3-none-any.whl → 3.0.0__py3-none-any.whl

meerschaum/connectors/instance/_tokens.py

@@ -0,0 +1,317 @@
+#! /usr/bin/env python3
+# vim:fenc=utf-8
+
+"""
+Define the high level tokens instance methods.
+"""
+
+from __future__ import annotations
+
+from typing import List, Union, Optional, Dict
+import uuid
+from datetime import datetime, timezone
+
+import meerschaum as mrsm
+from meerschaum.core import Token, User
+from meerschaum.core.User import hash_password
+from meerschaum._internal.static import STATIC_CONFIG
+from meerschaum.utils.warnings import dprint
+
+
+def get_tokens_pipe(self) -> mrsm.Pipe:
+    """
+    Return the internal pipe for tokens management.
+    """
+    if '_tokens_pipe' in self.__dict__:
+        return self._tokens_pipe
+
+    users_pipe = self.get_users_pipe()
+    user_id_dtype = (
+        users_pipe._attributes.get('parameters', {}).get('dtypes', {}).get('user_id', 'uuid')
+    )
+
+    cache_connector = self.__dict__.get('_cache_connector', None)
+
+    self._tokens_pipe = mrsm.Pipe(
+        'mrsm', 'tokens',
+        instance=self,
+        target='mrsm_tokens',
+        temporary=True,
+        cache=True,
+        cache_connector_keys=cache_connector,
+        static=True,
+        autotime=True,
+        null_indices=False,
+        columns={
+            'datetime': 'creation',
+            'primary': 'id',
+        },
+        indices={
+            'unique': 'label',
+            'user_id': 'user_id',
+        },
+        dtypes={
+            'id': 'uuid',
+            'creation': 'datetime',
+            'expiration': 'datetime',
+            'is_valid': 'bool',
+            'label': 'string',
+            'user_id': user_id_dtype,
+            'scopes': 'json',
+            'secret_hash': 'string',
+        },
+    )
+    return self._tokens_pipe
+
+
+def register_token(
+    self,
+    token: Token,
+    debug: bool = False,
+) -> mrsm.SuccessTuple:
+    """
+    Register the new token to the tokens table.
+    """
+    token_id, token_secret = token.generate_credentials()
+    tokens_pipe = self.get_tokens_pipe()
+    user_id = self.get_user_id(token.user) if token.user is not None else None
+    if user_id is None:
+        return False, "Cannot register a token without a user."
+
+    doc = {
+        'id': token_id,
+        'user_id': user_id,
+        'creation': datetime.now(timezone.utc),
+        'expiration': token.expiration,
+        'label': token.label,
+        'is_valid': token.is_valid,
+        'scopes': list(token.scopes) if token.scopes else [],
+        'secret_hash': hash_password(
+            str(token_secret),
+            rounds=STATIC_CONFIG['tokens']['hash_rounds']
+        ),
+    }
+    sync_success, sync_msg = tokens_pipe.sync([doc], check_existing=False, debug=debug)
+    if not sync_success:
+        return False, f"Failed to register token:\n{sync_msg}"
+    return True, "Success"
+
+
+def edit_token(self, token: Token, debug: bool = False) -> mrsm.SuccessTuple:
+    """
+    Persist the token's in-memory state to the tokens pipe.
+    """
+    if not token.id:
+        return False, "Token ID is not set."
+
+    if not token.exists(debug=debug):
+        return False, f"Token {token.id} does not exist."
+
+    if not token.creation:
+        token_model = self.get_token_model(token.id)
+        token.creation = token_model.creation
+
+    tokens_pipe = self.get_tokens_pipe()
+    doc = {
+        'id': token.id,
+        'creation': token.creation,
+        'expiration': token.expiration,
+        'label': token.label,
+        'is_valid': token.is_valid,
+        'scopes': list(token.scopes) if token.scopes else [],
+    }
+    sync_success, sync_msg = tokens_pipe.sync([doc], debug=debug)
+    if not sync_success:
+        return False, f"Failed to edit token '{token.id}':\n{sync_msg}"
+
+    return True, "Success"
+
+
+def invalidate_token(self, token: Token, debug: bool = False) -> mrsm.SuccessTuple:
+    """
+    Set `is_valid` to `False` for the given token.
+    """
+    if not token.id:
+        return False, "Token ID is not set."
+
+    if not token.exists(debug=debug):
+        return False, f"Token {token.id} does not exist."
+
+    if not token.creation:
+        token_model = self.get_token_model(token.id)
+        token.creation = token_model.creation
+
+    token.is_valid = False
+    tokens_pipe = self.get_tokens_pipe()
+    doc = {
+        'id': token.id,
+        'creation': token.creation,
+        'is_valid': False,
+    }
+    sync_success, sync_msg = tokens_pipe.sync([doc], debug=debug)
+    if not sync_success:
+        return False, f"Failed to invalidate token '{token.id}':\n{sync_msg}"
+
+    return True, "Success"
+
+
+def delete_token(self, token: Token, debug: bool = False) -> mrsm.SuccessTuple:
+    """
+    Delete the given token from the tokens table.
+    """
+    if not token.id:
+        return False, "Token ID is not set."
+
+    if not token.exists(debug=debug):
+        return False, f"Token {token.id} does not exist."
+
+    if not token.creation:
+        token_model = self.get_token_model(token.id)
+        token.creation = token_model.creation
+
+    token.is_valid = False
+    tokens_pipe = self.get_tokens_pipe()
+    clear_success, clear_msg = tokens_pipe.clear(params={'id': token.id}, debug=debug)
+    if not clear_success:
+        return False, f"Failed to delete token '{token.id}':\n{clear_msg}"
+
+    return True, "Success"
+
+
+def get_tokens(
+    self,
+    user: Optional[User] = None,
+    labels: Optional[List[str]] = None,
+    ids: Optional[List[uuid.UUID]] = None,
+    debug: bool = False,
+) -> List[Token]:
+    """
+    Return a list of `Token` objects.
+    """
+    tokens_pipe = self.get_tokens_pipe()
+    user_id = (
+        self.get_user_id(user, debug=debug)
+        if user is not None
+        else None
+    )
+    user_type = self.get_user_type(user, debug=debug) if user is not None else None
+    params = (
+        {
+            'user_id': (
+                user_id
+                if user_type != 'admin'
+                else [user_id, None]
+            )
+        }
+        if user_id is not None
+        else {}
+    )
+    if labels:
+        params['label'] = labels
+    if ids:
+        params['id'] = ids
+        
+    if debug:
+        dprint(f"Getting tokens with {user_id=}, {params=}")
+
+    tokens_df = tokens_pipe.get_data(params=params, debug=debug)
+    if tokens_df is None:
+        return []
+
+    if debug:
+        dprint(f"Retrieved tokens dataframe:\n{tokens_df}")
+
+    tokens_docs = tokens_df.to_dict(orient='records')
+    return [
+        Token(
+            instance=self,
+            **token_doc
+        )
+        for token_doc in reversed(tokens_docs)
+    ]
+
+
+def get_token(self, token_id: Union[uuid.UUID, str], debug: bool = False) -> Union[Token, None]:
+    """
+    Return the `Token` from its ID.
+    """
+    from meerschaum.utils.misc import is_uuid
+    if isinstance(token_id, str):
+        if is_uuid(token_id):
+            token_id = uuid.UUID(token_id)
+        else:
+            raise ValueError("Invalid token ID.")
+    token_model = self.get_token_model(token_id)
+    if token_model is None:
+        return None
+    return Token(**dict(token_model))
+
+
+def get_token_model(self, token_id: Union[uuid.UUID, Token], debug: bool = False) -> 'Union[TokenModel, None]':
+    """
+    Return a token's model from the instance.
+    """
+    from meerschaum.models import TokenModel
+    if isinstance(token_id, Token):
+        token_id = Token.id
+    if not token_id:
+        raise ValueError("Invalid token ID.")
+    tokens_pipe = self.get_tokens_pipe()
+    doc = tokens_pipe.get_doc(
+        params={'id': token_id},
+        debug=debug,
+    )
+    if doc is None:
+        return None
+    return TokenModel(**doc)
+
+
+def get_token_secret_hash(self, token_id: Union[uuid.UUID, Token], debug: bool = False) -> Union[str, None]:
+    """
+    Return the secret hash for a given token.
+    """
+    if isinstance(token_id, Token):
+        token_id = token_id.id
+    if not token_id:
+        raise ValueError("Invalid token ID.")
+    tokens_pipe = self.get_tokens_pipe()
+    return tokens_pipe.get_value('secret_hash', params={'id': token_id}, debug=debug)
+
+
+def get_token_user_id(self, token_id: Union[uuid.UUID, Token], debug: bool = False) -> Union[int, str, uuid.UUID, None]:
+    """
+    Return a token's user_id.
+    """
+    if isinstance(token_id, Token):
+        token_id = token_id.id
+    if not token_id:
+        raise ValueError("Invalid token ID.")
+
+    tokens_pipe = self.get_tokens_pipe()
+    return tokens_pipe.get_value('user_id', params={'id': token_id}, debug=debug)
+
+
+def get_token_scopes(self, token_id: Union[uuid.UUID, Token], debug: bool = False) -> List[str]:
+    """
+    Return the scopes for a token.
+    """
+    if isinstance(token_id, Token):
+        token_id = token_id.id
+    if not token_id:
+        raise ValueError("Invalid token ID.")
+
+    tokens_pipe = self.get_tokens_pipe()
+    return tokens_pipe.get_value('scopes', params={'id': token_id}, debug=debug) or []
+
+
+def token_exists(self, token_id: Union[uuid.UUID, Token], debug: bool = False) -> bool:
+    """
+    Return `True` if a token exists in the tokens pipe.
+    """
+    if isinstance(token_id, Token):
+        token_id = token_id.id
+    if not token_id:
+        raise ValueError("Invalid token ID.")
+
+    tokens_pipe = self.get_tokens_pipe()
+    return tokens_pipe.get_value('creation', params={'id': token_id}, debug=debug) is not None

meerschaum/connectors/instance/_users.py

@@ -0,0 +1,188 @@
+#! /usr/bin/env python3
+# vim:fenc=utf-8
+
+"""
+Define high-level user-management methods for instance connectors.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Union, Optional, List, Dict
+
+import meerschaum as mrsm
+from meerschaum.core import User
+
+
+def get_users_pipe(self) -> 'mrsm.Pipe':
+    """
+    Return the pipe used for users registration.
+    """
+    if '_users_pipe' in self.__dict__:
+        return self._users_pipe
+
+    cache_connector = self.__dict__.get('_cache_connector', None)
+    self._users_pipe = mrsm.Pipe(
+        'mrsm', 'users',
+        instance=self,
+        target='mrsm_users',
+        temporary=True,
+        cache=True,
+        cache_connector_keys=cache_connector,
+        static=True,
+        null_indices=False,
+        columns={
+            'primary': 'user_id',
+        },
+        dtypes={
+            'user_id': 'uuid',
+            'username': 'string',
+            'password_hash': 'string',
+            'email': 'string',
+            'user_type': 'string',
+            'attributes': 'json',
+        },
+        indices={
+            'unique': 'username',
+        },
+    )
+    return self._users_pipe
+
+
+def register_user(
+    self,
+    user: User,
+    debug: bool = False,
+    **kwargs: Any
+) -> mrsm.SuccessTuple:
+    """
+    Register a new user to the users pipe.
+    """
+    users_pipe = self.get_users_pipe()
+    user.user_id = uuid.uuid4()
+    sync_success, sync_msg = users_pipe.sync(
+        [{
+            'user_id': user.user_id,
+            'username': user.username,
+            'email': user.email,
+            'password_hash': user.password_hash,
+            'user_type': user.type,
+            'attributes': user.attributes,
+        }],
+        check_existing=False,
+        debug=debug,
+    )
+    if not sync_success:
+        return False, f"Failed to register user '{user.username}':\n{sync_msg}"
+
+    return True, "Success"
+
+
+def get_user_id(self, user: User, debug: bool = False) -> Union[uuid.UUID, None]:
+    """
+    Return a user's ID from the username.
+    """
+    users_pipe = self.get_users_pipe()
+    result_df = users_pipe.get_data(['user_id'], params={'username': user.username}, limit=1)
+    if result_df is None or len(result_df) == 0:
+        return None
+    return result_df['user_id'][0]
+
+
+def get_username(self, user_id: Any, debug: bool = False) -> Any:
+    """
+    Return the username from the given ID.
+    """
+    users_pipe = self.get_users_pipe()
+    return users_pipe.get_value('username', {'user_id': user_id}, debug=debug)
+
+
+def get_users(
+    self,
+    debug: bool = False,
+    **kw: Any
+) -> List[str]:
+    """
+    Get the registered usernames.
+    """
+    users_pipe = self.get_users_pipe()
+    df = users_pipe.get_data()
+    if df is None:
+        return []
+
+    return list(df['username'])
+
+
+def edit_user(self, user: User, debug: bool = False) -> mrsm.SuccessTuple:
+    """
+    Edit the attributes for an existing user.
+    """
+    users_pipe = self.get_users_pipe()
+    user_id = user.user_id if user.user_id is not None else self.get_user_id(user, debug=debug)
+
+    doc = {'user_id': user_id}
+    if user.email != '':
+        doc['email'] = user.email
+    if user.password_hash != '':
+        doc['password_hash'] = user.password_hash
+    if user.type != '':
+        doc['user_type'] = user.type
+    if user.attributes:
+        doc['attributes'] = user.attributes
+
+    sync_success, sync_msg = users_pipe.sync([doc], debug=debug)
+    if not sync_success:
+        return False, f"Failed to edit user '{user.username}':\n{sync_msg}"
+
+    return True, "Success"
+
+
+def delete_user(self, user: User, debug: bool = False) -> mrsm.SuccessTuple:
+    """
+    Delete a user from the users table.
+    """
+    user_id = user.user_id if user.user_id is not None else self.get_user_id(user, debug=debug)
+    users_pipe = self.get_users_pipe()
+    clear_success, clear_msg = users_pipe.clear(params={'user_id': user_id}, debug=debug)
+    if not clear_success:
+        return False, f"Failed to delete user '{user}':\n{clear_msg}"
+    return True, "Success"
+
+
+def get_user_password_hash(self, user: User, debug: bool = False) -> Union[uuid.UUID, None]:
+    """
+    Get a user's password hash from the users table.
+    """
+    user_id = user.user_id if user.user_id is not None else self.get_user_id(user, debug=debug)
+    users_pipe = self.get_users_pipe()
+    result_df = users_pipe.get_data(['password_hash'], params={'user_id': user_id}, debug=debug)
+    if result_df is None or len(result_df) == 0:
+        return None
+
+    return result_df['password_hash'][0]
+
+
+def get_user_type(self, user: User, debug: bool = False) -> Union[str, None]:
+    """
+    Get a user's type from the users table.
+    """
+    user_id = user.user_id if user.user_id is not None else self.get_user_id(user, debug=debug)
+    users_pipe = self.get_users_pipe()
+    result_df = users_pipe.get_data(['user_type'], params={'user_id': user_id}, debug=debug)
+    if result_df is None or len(result_df) == 0:
+        return None
+
+    return result_df['user_type'][0]
+
+
+def get_user_attributes(self, user: User, debug: bool = False) -> Union[Dict[str, Any], None]:
+    """
+    Get a user's attributes from the users table.
+    """
+    user_id = user.user_id if user.user_id is not None else self.get_user_id(user, debug=debug)
+    users_pipe = self.get_users_pipe()
+    result_df = users_pipe.get_data(['attributes'], params={'user_id': user_id}, debug=debug)
+    if result_df is None or len(result_df) == 0:
+        return None
+
+    return result_df['attributes'][0]

meerschaum/connectors/parse.py

@@ -56,7 +56,7 @@ def parse_connector_keys(
     import copy
     from meerschaum.connectors import get_connector
     from meerschaum.config import get_config
-    from meerschaum.config.static import STATIC_CONFIG
+    from meerschaum._internal.static import STATIC_CONFIG
     from meerschaum.utils.warnings import error
 
     ### `get_connector()` handles the logic for falling back to 'main',
@@ -111,11 +111,14 @@ def parse_repo_keys(keys: Optional[str] = None, **kw):
     """Parse the Meerschaum repository value into an APIConnector."""
     from meerschaum.config import get_config
     if keys is None:
-        keys = get_config('meerschaum', 'default_repository', patch=True)
+        keys = get_config('meerschaum', 'repository', patch=True)
     keys = str(keys)
     if ':' not in keys:
         keys = 'api:' + keys
 
+    if not keys.startswith('api:'):
+        raise ValueError("Only APIConnectors may be treated as repositories.")
+
     return parse_connector_keys(keys, **kw)
 
 

meerschaum/connectors/sql/_SQLConnector.py

@@ -7,14 +7,16 @@ Interface with SQL servers using sqlalchemy.
 """
 
 from __future__ import annotations
+
+import pathlib
 import meerschaum as mrsm
 from meerschaum.utils.typing import Optional, Any, Union
 
-from meerschaum.connectors import Connector
+from meerschaum.connectors import InstanceConnector
 from meerschaum.utils.warnings import error, warn
 
 
-class SQLConnector(Connector):
+class SQLConnector(InstanceConnector):
     """
     Connect to SQL databases via `sqlalchemy`.
     
@@ -24,8 +26,6 @@ class SQLConnector(Connector):
 
     """
 
-    IS_INSTANCE: bool = True
-
     from ._create_engine import flavor_configs, create_engine
     from ._sql import (
         read,
@@ -75,6 +75,7 @@ class SQLConnector(Connector):
         get_pipe_index_names,
     )
     from ._plugins import (
+        get_plugins_pipe,
         register_plugin,
         delete_plugin,
         get_plugin_id,
@@ -85,6 +86,7 @@ class SQLConnector(Connector):
         get_plugin_attributes,
     )
     from ._users import (
+        get_users_pipe,
         register_user,
         get_user_id,
         get_users,
@@ -151,6 +153,9 @@ class SQLConnector(Connector):
             if uri.startswith('timescaledb://'):
                 uri = uri.replace('timescaledb://', 'postgresql+psycopg://', 1)
                 flavor = 'timescaledb'
+            if uri.startswith('timescaledb-ha://'):
+                uri = uri.replace('timescaledb-ha://', 'postgresql+psycopg://', 1)
+                flavor = 'timescaledb-ha'
             if uri.startswith('postgis://'):
                 uri = uri.replace('postgis://', 'postgresql+psycopg://', 1)
                 flavor = 'postgis'
@@ -313,7 +318,7 @@ class SQLConnector(Connector):
         """
         Return the schema name for internal tables. 
         """
-        from meerschaum.config.static import STATIC_CONFIG
+        from meerschaum._internal.static import STATIC_CONFIG
         from meerschaum.utils.sql import NO_SCHEMA_FLAVORS
         schema_name = self.__dict__.get('internal_schema', None) or (
             STATIC_CONFIG['sql']['internal_schema']
@@ -373,6 +378,18 @@ class SQLConnector(Connector):
         self.__dict__['schema'] = _schema
         return _schema
 
+    def get_metadata_cache_path(self, kind: str = 'json') -> pathlib.Path:
+        """
+        Return the path to the file to which to write metadata cache.
+        """
+        from meerschaum.config.paths import SQL_CONN_CACHE_RESOURCES_PATH
+        filename = (
+            f'{self.label}-metadata.pkl'
+            if kind == 'pkl'
+            else f'{self.label}.json'
+        )
+        return SQL_CONN_CACHE_RESOURCES_PATH / filename
+
     def __getstate__(self):
         return self.__dict__
 

meerschaum/connectors/sql/_cli.py

@@ -14,17 +14,18 @@ import copy
 from meerschaum.utils.typing import SuccessTuple
 
 flavor_clis = {
-    'postgresql'  : 'pgcli',
-    'postgis'  : 'pgcli',
-    'timescaledb' : 'pgcli',
-    'cockroachdb' : 'pgcli',
-    'citus'       : 'pgcli',
-    'mysql'       : 'mycli',
-    'mariadb'     : 'mycli',
-    'percona'     : 'mycli',
-    'sqlite'      : 'litecli',
-    'mssql'       : 'mssqlcli',
-    'duckdb'      : 'gadwall',
+    'postgresql'     : 'pgcli',
+    'postgis'        : 'pgcli',
+    'timescaledb'    : 'pgcli',
+    'timescaledb-ha' : 'pgcli',
+    'cockroachdb'    : 'pgcli',
+    'citus'          : 'pgcli',
+    'mysql'          : 'mycli',
+    'mariadb'        : 'mycli',
+    'percona'        : 'mycli',
+    'sqlite'         : 'litecli',
+    'mssql'          : 'mssqlcli',
+    'duckdb'         : 'gadwall',
 }
 cli_deps = {
     'pgcli': ['pgspecial', 'pendulum', 'cli_helpers'],