qmenta-core 4.1.1.dev716__tar.gz

qmenta_core-4.1.1.dev716/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.3
+Name: qmenta-core
+Version: 4.1.1.dev716
+Summary: QMENTA core library to communicate with the QMENTA platform.
+License: Proprietary
+Author: QMENTA
+Author-email: dev@qmenta.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: blinker (>=1.4,<2.0)
+Requires-Dist: importlib-metadata (>=6.8.0,<7.0.0)
+Requires-Dist: packaging (>=25.0,<26.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: qmenta-anon (>=2.1.dev377,<3.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: xdg (>=6.0.0,<7.0.0)
+Project-URL: Documentation, https://docs.qmenta.com/core/
+Project-URL: Homepage, https://www.qmenta.com/
+Description-Content-Type: text/markdown
+
+# QMENTA Core
+This Python library contains core functionality for communicating with
+the QMENTA platform.
+

qmenta_core-4.1.1.dev716/README.md

@@ -0,0 +1,3 @@
+# QMENTA Core
+This Python library contains core functionality for communicating with
+the QMENTA platform.

qmenta_core-4.1.1.dev716/pyproject.toml

@@ -0,0 +1,61 @@
+[tool.poetry]
+name = "qmenta-core"
+version = "4.1.1.dev716"
+description = "QMENTA core library to communicate with the QMENTA platform."
+license = "Proprietary"
+authors = ["QMENTA <dev@qmenta.com>"]
+readme = "README.md"
+homepage = "https://www.qmenta.com/"
+documentation = "https://docs.qmenta.com/core/"
+classifiers=[
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+]
+packages = [
+    { include = "qmenta", from = "src" }
+]
+
+[tool.poetry.scripts]
+qmenta-auth = 'qmenta.core.auth:main'
+
+[tool.poetry.dependencies]
+python = "^3.10"
+requests = "^2.31.0"
+pyyaml = "^6.0.1"
+qmenta-anon = "^2.1.dev377"
+importlib-metadata = "^6.8.0"
+xdg = "^6.0.0"
+python-dotenv = "^1.0.0"
+# We are not requiring the latest blinker 1.6.2 because that is not
+#   available in Google Colab, see EN-1810.
+blinker = "^1.4"
+packaging = "^25.0"
+
+[tool.poetry.group.dev.dependencies]
+flake8 = "^6.1.0"
+mypy = "^1.5.1"
+pytest = "^7.4.0"
+coverage = {version = "^7.3.0", extras = ["toml"]}
+pytest-cov = "^6.1.1"
+sphinx-rtd-theme = "^1.3.0"
+dom-toml = "^0.6.1"
+scriv = {version = "^1.3.1", extras = ["toml"]}
+types-requests = "^2.31.0.2"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.coverage.report]
+fail_under = 90
+
+[tool.scriv]
+format = "md"
+md_header_level = "2"
+insert_marker = "scriv-insert-here"
+
+[tool.mypy]
+mypy_path = "src"
+strict = true
+ignore_missing_imports = true
+disallow_untyped_calls = false

qmenta_core-4.1.1.dev716/src/qmenta/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

qmenta_core-4.1.1.dev716/src/qmenta/core/.gitignore

@@ -0,0 +1 @@
+VERSION

qmenta_core-4.1.1.dev716/src/qmenta/core/__init__.py

@@ -0,0 +1,10 @@
+from importlib_metadata import version, PackageNotFoundError
+
+__version__: str
+try:
+    __version__ = version('qmenta-core')
+except PackageNotFoundError:
+    # Package not installed. Using a local dev version.
+    __version__ = "0.0dev0"
+
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

qmenta_core-4.1.1.dev716/src/qmenta/core/auth.py

@@ -0,0 +1,342 @@
+import argparse
+from enum import Enum, unique
+import os
+import requests
+from getpass import getpass
+from pathlib import Path
+from typing import Optional, Dict
+from urllib.parse import urljoin, urlparse
+
+from xdg import xdg_data_home
+from dotenv import load_dotenv
+
+from qmenta.core.errors import (
+    ActionFailedError,
+    ConnectionError,
+    InvalidResponseError,
+    PlatformError
+)
+
+
+class InvalidLoginError(ActionFailedError):
+    """
+    When the provided credentials are incorrect, or when the used token
+    is not valid.
+    """
+    pass
+
+
+class Needs2FAError(ActionFailedError):
+    """
+    When a 2FA code must to be provided to log in.
+    """
+    pass
+
+
+@unique
+class PlatformURL(Enum):
+    platform = 'https://platform.qmenta.com'
+    staging = 'https://staging.qmenta.com'
+    test = 'https://test.qmenta.com'
+    test_insecure = 'http://test.qmenta.com'
+    local_ip = "http://127.0.0.1:8080"
+    localhost = "http://localhost:8080"
+
+
+class Auth:
+    """
+    Class for authenticating to the platform.
+    Do not use the constructor directly, but use the login() function to
+    create a new authentication.
+
+    Attributes
+    ----------
+    base_url : str
+        The URL of the platform to connect to.
+        Default value: 'https://platform.qmenta.com'
+    token : str
+        The authentication token, returned by the platform when logging in.
+    """
+    def __init__(self, base_url: str, token: str) -> None:
+        validate_url(base_url)
+        self.base_url = base_url
+        self.token = token
+        self._session: Optional[requests.Session] = None
+
+    @staticmethod
+    def qmenta_auth_env_file() -> Path:
+        """
+        Return the path of the qmenta auth env file
+        """
+        return xdg_data_home() / 'QMENTA' / 'auth' / '.env'
+
+    @classmethod
+    def from_env(cls, dot_env: Optional[Path] = None) -> 'Auth':
+        """
+        Create an Auth object using the QMENTA_URL and QMENTA_AUTH_TOKEN
+        environment variables.
+        If the variables are not set in the environment, but they exist in
+        the file dot_env, then those values are used.
+
+        This function can be used to create an Auth object in scripts to
+        communicate with QMENTA Platform, after the `qmenta-auth` command
+        has been run to authenticate.
+
+        Parameters
+        ----------
+        dot_env: Path
+            The location of the .env file to read the environment variables.
+            If no value is supplied, qmenta_auth_env_file() is used as
+            the default value. (Optional)
+
+        Raises
+        ------
+        InvalidLoginError
+            When one of the needed environment variables was not found
+        """
+
+        # Loads variables from the .env file, but does NOT override existing
+        #   values already set in the environment.
+        # No exception is raised if the file is not found.
+        dotenv_file = dot_env or cls.qmenta_auth_env_file()
+        load_dotenv(dotenv_file)
+
+        try:
+            token: str = os.environ["QMENTA_AUTH_TOKEN"]
+            url: str = os.environ["QMENTA_URL"]
+        except KeyError as e:
+            raise InvalidLoginError(f'Missing environment variable: {e}')
+
+        print(f'Using authentication token for {url}')
+        return cls(url, token)
+
+    @classmethod
+    def login(cls, username: str, password: str,
+              code_2fa: Optional[str] = None,
+              ask_for_2fa_input: bool = False,
+              base_url: str = PlatformURL.platform.value) -> 'Auth':
+        """
+        Authenticate to the platform using username and password.
+
+        Parameters
+        ----------
+        username : str
+            The username to log in on the platform. For all new platform
+            accounts, this is the e-mail address of the user.
+            Example: 'example@qmenta.com'
+        password : str
+            The QMENTA platform password of the user.
+        code_2fa : str
+            The 2FA code that was sent to your phone (optional).
+        ask_for_2fa_input: bool
+            When set to True, the user is asked input the 2FA code
+            in the command-line interface when it is needed. If the user does
+            not have 2FA enabled, no input is requested.
+            This is useful for scripts.
+            When set to False, a Needs2FAError exception is raised when
+            a 2FA code is needed. This is useful for GUIs.
+            Default value: False
+        base_url : str
+            The URL of the platform to connect to.
+            Default value: 'https://platform.qmenta.com'
+
+        Returns
+        -------
+        Auth
+            The Auth object that was logged in with.
+
+        Raises
+        ------
+        ConnectionError
+            If there was a problem setting up the network connection with the
+            platform and for 404 and 5xx response status code.
+        InvalidResponseError
+            If the platform returned an invalid response.
+        InvalidLoginError
+            If the login was invalid. This can happen when the
+            username/password combination is incorrect, or when the account is
+            not active or 2FA is required to be set up.
+        Needs2FAError
+            When a login attempt was done without a valid 2FA code.
+            The 2FA code has been sent to your phone, and must be provided
+            in the next call to the login function.
+        """
+        url: str = urljoin(base_url, '/login')
+
+        try:
+            response: requests.Response = requests.post(
+                url, data={
+                    'username': username, 'password': password,
+                    'code_2fa': code_2fa
+                }
+            )
+            # Raises an exception for 4xx and 5xx status codes
+            response.raise_for_status()
+            # Assuming the response contains JSON data
+            data: dict = response.json()
+            # Process the data here
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                raise ConnectionError("API returned a 404 error: Not Found")
+            else:
+                raise ConnectionError("API returned an error:", e)
+        except InvalidResponseError as e:
+            raise InvalidResponseError("Invalid Response Error:", e)
+        except requests.RequestException as e:
+            raise ConnectionError(str(e))
+        except Exception as e:
+            raise Exception("An error occurred:", e)
+
+        try:
+            if data["success"] != 1:
+                # Login was not successful
+                if data.get("account_state", "") == '2fa_need':
+                    if ask_for_2fa_input:
+                        input_2fa = input("Please enter your 2FA code: ")
+                        return Auth.login(
+                            username, password, code_2fa=input_2fa,
+                            ask_for_2fa_input=True, base_url=base_url
+                        )
+                    else:
+                        raise Needs2FAError(
+                            'Provide the 2FA code sent to your phone, '
+                            'or set the ask_for_2fa_input parameter'
+                        )
+                else:
+                    raise InvalidLoginError(data['error'])
+
+            token: str = data['token']
+        except KeyError as e:
+            raise InvalidResponseError(f'Missing key: {e}')
+
+        return cls(base_url, token)
+
+    def get_session(self) -> requests.Session:
+        if not self._session:
+            self._session = requests.Session()
+
+            # Session may store other cookies such as 'route'
+            auth_cookie = requests.cookies.create_cookie(
+                name='AUTH_COOKIE', value=self.token
+            )
+            # Add or update it
+            self._session.cookies.set_cookie(auth_cookie)
+            self._session.headers.update(self._headers())
+
+        return self._session
+
+    def _headers(self) -> Dict[str, str]:
+        h = {
+            'Mint-Api-Call': '1'
+        }
+        return h
+
+
+def write_dot_env_file(token: str, url: str,
+                       filename: Optional[Path] = None) -> None:
+    """
+    Write the token and URL to a .env file.
+
+    Parameters
+    ----------
+    token: str
+        The token to write to the .env file
+    url: str
+        The URL to write to the .env file
+    filename: Path
+        The filename of the .env file to write to (optional).
+        If no value is supplied, it will be written to the default
+        location qmenta_auth_env_file().
+
+    Raises
+    ------
+    OSError
+        When the output file could not be written
+    """
+    validate_url(url)
+
+    filepath = filename or Auth.qmenta_auth_env_file()
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+
+    with open(filepath, 'w') as envFile:
+        print(f'QMENTA_URL={url}', file=envFile)
+        print(f'QMENTA_AUTH_TOKEN={token}', file=envFile)
+
+    print(f'Auth token was written to {filepath}')
+
+
+def validate_url(url: str) -> None:
+    """
+    Validate the URL as a valid http or https URL.
+
+    Raises
+    ------
+    ValueError
+        When the URL is not valid
+    """
+
+    parsed_url = urlparse(url)
+
+    if parsed_url.scheme == 'http':
+        print('WARNING: Only use http for local testing.')
+    elif not parsed_url.scheme == 'https':
+        raise ValueError(
+            'URL should start with https://. '
+            'Example: https://platform.menta.com'
+        )
+    if parsed_url.path not in ['', '/']:
+        raise ValueError(
+            'Provide only the root URL of the backend server. '
+            'Example: https://platform.qmenta.com'
+        )
+    if parsed_url.username or parsed_url.password or parsed_url.query:
+        raise ValueError(
+            'Provide only the root URL of the backend server. '
+            'Example: https://platform.qmenta.com'
+        )
+
+    url_values = [p_url.value for p_url in PlatformURL]
+    if parsed_url.scheme + '://' + parsed_url.netloc not in url_values:
+        raise ValueError(
+            "base_url must be one of '{}', ".format("', '".join(url_values))
+            + f"not '{parsed_url.netloc}'."
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            'Log in on QMENTA platform and store the authentication '
+            'token in a .env file. Username and password may be '
+            'provided as parameters, or will be asked as user input. '
+        )
+    )
+    parser.add_argument('--username', help='Username to login',)
+    parser.add_argument('--password', help='Password')
+    parser.add_argument(
+        'url', help='Platform URL, for example: https://platform.qmenta.com')
+    args = parser.parse_args()
+
+    try:
+        validate_url(args.url)
+    except ValueError as err:
+        print(err)
+        return
+
+    username = args.username or input("Username: ")
+    password = args.password or getpass()
+
+    try:
+        auth = Auth.login(
+            username=username, password=password,
+            ask_for_2fa_input=True, base_url=args.url
+        )
+    except PlatformError as err:
+        print(err)
+        return
+
+    write_dot_env_file(token=auth.token, url=auth.base_url)
+
+
+if __name__ == '__main__':  # pragma: no cover
+    main()

qmenta_core-4.1.1.dev716/src/qmenta/core/errors.py

@@ -0,0 +1,50 @@
+"""
+Define the root error class for all QMENTA exceptions. All exceptions raised
+by the QMENTA Core library are subclasses of ``qmenta.core.errors.Error`` and
+thus are expected exceptions. If other exceptions are raised, this indicates
+unexpected behavior of the library.
+"""
+
+
+class Error(Exception):
+    """
+    Base class for all QMENTA Core errors.
+    """
+    def __init__(self, *args: str) -> None:
+        Exception.__init__(self, *args)
+
+
+class CannotReadFileError(Error):
+    """
+    When a file cannot be read.
+    """
+    pass
+
+
+class PlatformError(Error):
+    """
+    When there is a problem in the communication with the platform.
+    """
+    pass
+
+
+class ConnectionError(PlatformError):
+    """
+    When there was a problem setting up the connection with QMENTA platform.
+    """
+    def __init__(self, message: str) -> None:
+        Error.__init__(self, f'Connection error: {message}')
+
+
+class InvalidResponseError(PlatformError):
+    """
+    The QMENTA platform returned an unexpected response.
+    """
+    pass
+
+
+class ActionFailedError(PlatformError):
+    """
+    When the requested action was not successful.
+    """
+    pass

qmenta_core-4.1.1.dev716/src/qmenta/core/platform.py

@@ -0,0 +1,185 @@
+import requests
+from qmenta.core.auth import Auth
+from qmenta.core.errors import (
+    ActionFailedError,
+    ConnectionError,
+    InvalidResponseError,
+)
+from typing import Dict, Any, List
+from urllib.parse import urljoin
+
+"""
+Handles all the communication with the QMENTA platform.
+"""
+
+
+class ChooseDataError(ActionFailedError):
+    """
+    When a trying to start an analysis, but data has to be chosen
+
+    Parameters
+    ----------
+    warning : str
+        Warning message returned by the platform
+    data_to_choose : dict
+        Specification of the data to choose returned by the platform
+    analysis_id : int
+        The ID of the analysis for which data needs to be chosen,
+        returned by the platform.
+    """
+
+    def __init__(
+        self, warning: str, data_to_choose: Dict[str, List[str]],
+        analysis_id: int
+    ) -> None:
+        self.warning: str = warning
+        self.data_to_choose: dict = data_to_choose
+        self.analysis_id: int = analysis_id
+
+
+def _raise_for_success_value(r: Dict[str, Any]) -> None:
+    """
+    Raise the appropriate exception depending on the value of success in
+    the response dict
+
+    Parameters
+    ----------
+    r : dict
+        The dict that was returned by the platform
+
+    Raises
+    ------
+    InvalidResponseError
+        When the response of the platform cannot be converted to JSON,
+        or when it has unexpected values or missing keys.
+    ActionFailedError
+        When the requested action could not be performed by the platform
+    ChooseDataError
+        When a POST was done to start an analysis, but data needs to be
+        chosen before the analysis can be started.
+    """
+    try:
+        success: int = r['success']
+        if success == 0:
+            raise ActionFailedError(r['error'])
+        if success == 1:
+            # Good!
+            pass
+        elif success == 2:
+            # You have to choose data
+            raise ChooseDataError(
+                warning=r['warning'],
+                data_to_choose=r['data_to_choose'],
+                analysis_id=r['analysis_id']
+            )
+        elif success == 3:
+            raise ActionFailedError(r['message'])
+        else:
+            raise InvalidResponseError(
+                'Unexpected value for success: {}'.format(success)
+            )
+    except KeyError as e:
+        raise InvalidResponseError('Missing key: {}'.format(e))
+
+
+def parse_response(response: requests.Response) -> Any:
+    """
+    Convert a platform response to JSON and check that it is valid.
+    This function should be applied to the output of post().
+
+    Parameters
+    ----------
+    response : requests.Response
+        The response from the platform
+
+    Raises
+    ------
+    InvalidResponseError
+        When the response of the platform cannot be converted to JSON,
+        or when it has unexpected values or missing keys.
+    ActionFailedError
+        When the requested action could not be performed by the platform
+    ChooseDataError
+        When a POST was done to start an analysis, but data needs to be
+        chosen before the analysis can be started.
+
+    Returns
+    -------
+    dict or list
+        When the platform returns a response with a list in the JSON, it
+        is returned. Otherwise, it is assumed that the returned value is a
+        dict. In case the dict has a 'data' key, the value of data in the
+        dict is returned, otherwise the full dict is returned.
+    """
+    try:
+        d: Any = response.json()
+    except ValueError:
+        raise InvalidResponseError(
+            'Could not decode JSON for response {}'.format(response))
+
+    if isinstance(d, dict):
+        _raise_for_success_value(d)
+        assert d['success'] == 1
+        if 'data' in d:
+            return d['data']
+        else:
+            return d
+    elif isinstance(d, list):
+        # In some cases, the platform does not return a dict with additional
+        #   information, but only a list with the results.
+        result = d
+    else:
+        raise InvalidResponseError(
+            'Response is not a dict or list: {}'.format(response.text))
+
+    return result
+
+
+def post(
+    auth: Auth, endpoint: str, data: Dict[str, Any] = {},
+    headers: Dict[str, Any] = {}, stream: bool = False,
+    timeout: float = 60.0
+) -> requests.Response:
+    """
+    Post the given data and headers to the specified platform's endpoint.
+
+    Parameters
+    ----------
+    auth : qmenta.core.platform.Auth
+        Auth object that was used to authenticate to the QMENTA platform
+    endpoint : str
+        The end-point in the platform to post to
+    data : dict
+        The data to post
+    headers : dict
+        The headers to post
+    stream : bool
+        Stream the response. This is used when downloading files.
+        Default value: False.
+    timeout : float
+        Timeout in seconds. If no bytes have been received within this time,
+        an exception is raised. Default value: 30.
+
+    Raises
+    ------
+    qmenta.core.errors.ConnectionError
+        When there is a problem connecting to the QMENTA platform
+
+    Returns
+    -------
+    requests.Response
+        The response object returned by the request.
+    """
+    url: str = urljoin(auth.base_url, endpoint)
+    try:
+        r = auth.get_session().post(
+            url=url,
+            data=data,
+            headers=headers,
+            stream=stream,
+            timeout=timeout
+        )
+    except requests.RequestException as e:
+        raise ConnectionError(str(e))
+
+    return r

qmenta_core-4.1.1.dev716/src/qmenta/core/upload/__init__.py

@@ -0,0 +1,4 @@
+from .single import FileInfo, UploadStatus, SingleUpload  # noqa
+from .multi import MultipleThreadedUploads  # noqa
+
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)