Added app API, example and tests

Author: Rasmus Oscar Welander

examples/app_api_example.py

@@ -0,0 +1,40 @@
+"""
+file_api_example.py
+
+Example script to demonstrate the usage of the app API in the CS3Client class.
+note that these are examples, and is not meant to be run as a script.
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: [email protected], [email protected], [email protected]
+Last updated: 19/08/2024
+"""
+
+import logging
+import configparser
+from cs3client import CS3Client
+from cs3resource import Resource
+
+config = configparser.ConfigParser()
+with open("default.conf") as fdef:
+    config.read_file(fdef)
+# log
+log = logging.getLogger(__name__)
+
+
+client = CS3Client(config, "cs3client", log)
+# client.auth.set_token("<your_token_here>")
+# OR
+client.auth.set_client_secret("<your_client_secret_here>")
+
+print(client.auth.get_token())
+
+# list_app_providers
+res = client.app.list_app_providers()
+if res is not None:
+    print(res)
+
+# open_in_app
+resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/collabora.odt")
+res = client.app.open_in_app(resource)
+if res is not None:
+    print(res)

src/app.py

@@ -0,0 +1,83 @@
+"""
+app.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: [email protected], [email protected], [email protected]
+Last updated: 19/08/2024
+"""
+
+import logging
+from auth import Auth
+from cs3resource import Resource
+import cs3.app.registry.v1beta1.registry_api_pb2 as cs3arreg
+import cs3.app.registry.v1beta1.resources_pb2 as cs3arres
+import cs3.gateway.v1beta1.gateway_api_pb2 as cs3gw
+import cs3.app.provider.v1beta1.resources_pb2 as cs3apr
+from cs3.gateway.v1beta1.gateway_api_pb2_grpc import GatewayAPIStub
+from statuscodehandler import StatusCodeHandler
+from config import Config
+
+
+class App:
+    """
+    App class to handle app related API calls with CS3 Gateway API.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        log: logging.Logger,
+        gateway: GatewayAPIStub,
+        auth: Auth,
+        status_code_handler: StatusCodeHandler,
+    ) -> None:
+        """
+        Initializes the App class with configuration, logger, auth, and gateway stub,
+
+        :param config: Config object containing the configuration parameters.
+        :param log: Logger instance for logging.
+        :param gateway: GatewayAPIStub instance for interacting with CS3 Gateway.
+        :param auth: An instance of the auth class.
+        :param status_code_handler: An instance of the StatusCodeHandler class.
+        """
+        self._status_code_handler: StatusCodeHandler = status_code_handler
+        self._gateway: GatewayAPIStub = gateway
+        self._log: logging.Logger = log
+        self._config: Config = config
+        self._auth: Auth = auth
+
+    def open_in_app(self, resource: Resource, view_mode: str = None, app: str = None) -> cs3apr.OpenInAppURL:
+        """
+        Open a file in an app, given the resource, view mode (VIEW_MODE_VIEW_ONLY, VIEW_MODE_READ_ONLY,
+        VIEW_MODE_READ_WRITE, VIEW_MODE_PREVIEW), and app name.
+
+        :param resource: Resource object containing the resource information.
+        :param view_mode: View mode of the app.
+        :param app: App name.
+        :return: URL to open the file in the app.
+        :raises: AuthenticationException (Operation not permitted)
+        :raises: NotFoundException (Resource not found)
+        :raises: UnknownException (Unknown error)
+        """
+        view_mode_type = None
+        if view_mode:
+            view_mode_type = cs3gw.OpenInAppRequest.ViewMode.Value(view_mode)
+        req = cs3gw.OpenInAppRequest(ref=resource.ref, view_mode=view_mode_type, app=app)
+        res = self._gateway.OpenInApp(request=req, metadata=[self._auth.get_token()])
+        self._status_code_handler.handle_errors(res.status, "open in app", f"{resource.get_file_ref_str()}")
+        self._log.debug(f'msg="Invoked OpenInApp" {resource.get_file_ref_str()} trace="{res.status.trace}"')
+        return res.OpenInAppURL
+
+    def list_app_providers(self) -> list[cs3arres.ProviderInfo]:
+        """
+        list_app_providers lists all the app providers.
+
+        :return: List of app providers.
+        :raises: AuthenticationException (Operation not permitted)
+        :raises: UnknownException (Unknown error)
+        """
+        req = cs3arreg.ListAppProvidersRequest()
+        res = self._gateway.ListAppProviders(request=req, metadata=[self._auth.get_token()])
+        self._status_code_handler.handle_errors(res.status, "list app providers")
+        self._log.debug(f'msg="Invoked ListAppProviders" res_count="{len(res.providers)}" trace="{res.status.trace}"')
+        return res.providers

tests/test_app.py

@@ -0,0 +1,89 @@
+"""
+test_app.py
+
+Tests that the App class methods work as expected.
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: [email protected], [email protected], [email protected]
+Last updated: 19/08/2024
+"""
+
+from exceptions.exceptions import (
+    AuthenticationException,
+    NotFoundException,
+    UnknownException,
+)
+
+from cs3resource import Resource
+
+import cs3.rpc.v1beta1.code_pb2 as cs3code
+from fixtures import (  # noqa: F401 (they are used, the framework is not detecting it)
+    mock_config,
+    mock_logger,
+    mock_authentication,
+    mock_gateway,
+    app_instance,
+    mock_status_code_handler,
+)
+
+from unittest.mock import Mock, patch
+
+import pytest
+
+# Test cases for the App class
+# Test cases for the App class `list_app_providers` method using parameterized tests
+
+
+@pytest.mark.parametrize(
+    "status_code, status_message, expected_exception, providers",
+    [
+        (cs3code.CODE_OK, None, None, ["provider1", "provider2"]),
+        (cs3code.CODE_UNAUTHENTICATED, "error", AuthenticationException, None),
+        (cs3code.CODE_INTERNAL, "error", UnknownException, None),
+    ],
+)
+def test_list_app_providers(
+    app_instance, status_code, status_message, expected_exception, providers  # noqa: F811 (not a redefinition)
+):
+    mock_response = Mock()
+    mock_response.status.code = status_code
+    mock_response.status.message = status_message
+    mock_response.providers = providers
+
+    with patch.object(app_instance._gateway, "ListAppProviders", return_value=mock_response):
+        if expected_exception:
+            with pytest.raises(expected_exception):
+                app_instance.list_app_providers()
+        else:
+            result = app_instance.list_app_providers()
+            assert result == providers
+
+
+@pytest.mark.parametrize(
+    "status_code, status_message, expected_exception, open_in_app_url",
+    [
+        (cs3code.CODE_OK, None, None, "url"),
+        (cs3code.CODE_UNAUTHENTICATED, "error", AuthenticationException, None),
+        (cs3code.CODE_NOT_FOUND, "error", NotFoundException, None),
+        (cs3code.CODE_INTERNAL, "error", UnknownException, None),
+    ],
+)
+def test_open_in_app(
+    app_instance, status_code, status_message, expected_exception, open_in_app_url  # noqa: F811 (not a redefinition)
+):
+    resource = Resource.from_file_ref_and_endpoint(endpoint="", file="testfile")
+    view_mode = "VIEW_MODE_VIEW_ONLY"
+    app = "app"
+
+    mock_response = Mock()
+    mock_response.status.code = status_code
+    mock_response.status.message = status_message
+    mock_response.OpenInAppURL = open_in_app_url
+
+    with patch.object(app_instance._gateway, "OpenInApp", return_value=mock_response):
+        if expected_exception:
+            with pytest.raises(expected_exception):
+                app_instance.open_in_app(resource, view_mode, app)
+        else:
+            result = app_instance.open_in_app(resource, view_mode, app)
+            assert result == open_in_app_url