feat: add base classes and docs

.github/workflows/code_quality.yaml

@@ -58,8 +58,8 @@ jobs:
         with:
           os: ${{ job.os }}
           python-version: '3.11'
-          poetry-install-options: "--only=types --no-root"
-          poetry-export-options: "--only=types"
+          poetry-install-options: "--only=main --only=types --no-root"
+          poetry-export-options: "--only=main --only=types"
 
       - name: Check types
         run: poetry run mypy tesk/

.github/workflows/endpoint_test.yaml

@@ -43,4 +43,4 @@ jobs:
           done
           echo "API failed to start in time"
           exit 1
-...
+...

deployment/config.yaml

@@ -1,3 +1,4 @@
+---
 # FOCA configuration
 # Available in app context as attributes of `current_app.config.foca`
 # Automatically validated via FOCA
@@ -71,9 +72,10 @@ log:
 # Exception configuration
 # Cf. https://foca.readthedocs.io/en/latest/modules/foca.models.html#foca.models.config.ExceptionConfig
 exceptions:
-    required_members: [['detail'], ['status'], ['title']]
-    status_member: ['status']
-    exceptions: tesk.exceptions.exceptions
+  required_members: [['detail'], ['status'], ['title']]
+  status_member: ['status']
+  exceptions: tesk.exceptions.exceptions
 
 storeLogs:
   execution_trace: True
+...

docs/source/index.rst

@@ -4,11 +4,11 @@ TESK
 .. toctree::
    :maxdepth: 1
    :caption: TESK
-   
+
 .. mdinclude:: ../../README.md
 .. mdinclude:: ../tesintro.md
 
-.. Not adding a heading to separate deployment docs because 
+.. Not adding a heading to separate deployment docs because
 .. these md files already have heading.
 .. mdinclude:: ../../deployment/documentation/deployment.md
 .. mdinclude:: ../../deployment/documentation/integrated_wes_tes.md
@@ -19,7 +19,7 @@ Package contents
 
 .. toctree::
    :maxdepth: 2
-   :caption: package
+   :caption: API reference
 
    pages/tesk/modules
 

docs/source/pages/tesk/modules.rst

@@ -1,7 +1,14 @@
-tesk
+TESK
 ====
 
 .. toctree::
    :maxdepth: 4
+   :caption: Services (filer and taskmaster)
 
-   tesk
+   tesk.services
+
+.. toctree::
+   :maxdepth: 4
+   :caption: API
+
+   tesk.api

docs/source/pages/tesk/tesk.api.ga4gh.rst

@@ -0,0 +1,18 @@
+tesk.api.ga4gh package
+======================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tesk.api.ga4gh.tes
+
+Module contents
+---------------
+
+.. automodule:: tesk.api.ga4gh
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pages/tesk/tesk.api.ga4gh.tes.base.rst

@@ -0,0 +1,21 @@
+tesk.api.ga4gh.tes.base package
+===============================
+
+Submodules
+----------
+
+tesk.api.ga4gh.tes.base.base\_tesk\_request module
+--------------------------------------------------
+
+.. automodule:: tesk.api.ga4gh.tes.base.base_tesk_request
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: tesk.api.ga4gh.tes.base
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pages/tesk/tesk.api.ga4gh.tes.rst

@@ -0,0 +1,29 @@
+tesk.api.ga4gh.tes package
+==========================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tesk.api.ga4gh.tes.base
+
+Submodules
+----------
+
+tesk.api.ga4gh.tes.controllers module
+-------------------------------------
+
+.. automodule:: tesk.api.ga4gh.tes.controllers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: tesk.api.ga4gh.tes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pages/tesk/tesk.api.rst

@@ -0,0 +1,18 @@
+tesk.api package
+================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tesk.api.ga4gh
+
+Module contents
+---------------
+
+.. automodule:: tesk.api
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pages/tesk/tesk.rst

@@ -7,8 +7,36 @@ Subpackages
 .. toctree::
    :maxdepth: 4
 
+   tesk.api
    tesk.services
 
+Submodules
+----------
+
+tesk.app module
+---------------
+
+.. automodule:: tesk.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tesk.exceptions module
+----------------------
+
+.. automodule:: tesk.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tesk.tesk\_app module
+---------------------
+
+.. automodule:: tesk.tesk_app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

mypy.ini

@@ -10,5 +10,5 @@ ignore_missing_imports = True
 [mypy-connexion.*]
 ignore_missing_imports = True
 
-[mypy-foca]
+[mypy-foca.*]
 ignore_missing_imports = True

pyproject.toml

@@ -65,6 +65,7 @@ boto3-stubs = "^1.34.108"
 kubernetes-stubs = "^22.6.0.post1"
 mypy = "^1.10.0"
 types-botocore = "^1.0.2"
+types-pyyaml = "^6.0.12.20240311"
 types-requests = "^2.31.0.20240406"
 types-urllib3 = "^1.26.25.14"
 types-werkzeug = "^1.0.9"

tesk/api/ga4gh/tes/base/__init__.py

@@ -0,0 +1 @@
+"""Package for base class for TESK API request."""

tesk/api/ga4gh/tes/base/base_tesk_request.py

@@ -0,0 +1,53 @@
+"""Base class for the TES API request."""
+
+from abc import ABC, abstractmethod
+from typing import Any, final
+
+from pydantic import BaseModel
+
+from tesk.tesk_app import TeskApp
+
+
+class BaseTeskRequest(ABC, TeskApp):
+	"""Base class for the TES API.
+
+	This class is an abstract class that defines the common properties and
+	methods needed by all of the TES API endpoint business logic.
+
+	Notes: This initializes the parent class `TeskApp` and will give
+		all the subclasses access to the configuration object `conf` and
+		config path.
+	"""
+
+	def __init__(self) -> None:
+		"""Initializes the BaseTeskRequest class."""
+		super().__init__()
+
+	@abstractmethod
+	def api_response(self) -> BaseModel:
+		"""Returns the response as Pydantic model.
+
+		Should be implemented by the child class as final
+		business logic for the specific endpoint.
+
+		Returns:
+			BaseModel: API response for the specific endpoint.
+
+		Raises:
+			Exception: If API response break due to something unhandled.
+		"""
+		return BaseModel()
+
+	@final
+	def response(self) -> dict[str, Any]:
+		"""Returns serialized response.
+
+		Should be invoked by controller.
+
+		Returns:
+			dict: Serialized response for the specific endpoint.
+		"""
+		_response = self.api_response()
+		if not isinstance(_response, BaseModel):
+			raise TypeError('API response must be a Pydantic model.')
+		return _response.dict()

tesk/api/ga4gh/tes/models/validators/base/__init__.py

@@ -0,0 +1 @@
+"""Package for base class for custom pydantic validators."""

tesk/api/ga4gh/tes/models/validators/base/base_validator.py

@@ -0,0 +1,79 @@
+"""Base validator class, all custom validators must implement it."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from pydantic import ValidationError
+
+T = TypeVar('T')
+logger = logging.getLogger(__name__)
+
+
+class BaseValidator(ABC, Generic[T]):
+	"""Base custom validator class.
+
+	Base validator class for fields in Pydantic models,
+	if the field is empty, ie None, then it is returned as is without any validation.
+	otherwise the validation logic is applied to the field.
+	"""
+
+	@property
+	@abstractmethod
+	def error_message(self) -> str:
+		"""Returns the error message.
+
+		Returns:
+			str: The error message to be used when validation fails.
+		"""
+		pass
+
+	@abstractmethod
+	def validation_logic(self, value: T) -> bool:
+		"""Validation logic for the field.
+
+		Args:
+			value: The value of the field being validated.
+
+		Returns:
+			bool: True if the validation is successful, False otherwise.
+		"""
+		pass
+
+	def _raise_error(self, cls: Any, value: T) -> None:
+		"""Raise a validation error.
+
+		Args:
+			cls: The class being validated.
+			value: The value of the field being validated.
+
+		Raises:
+			ValidationError: Raised when the validation fails.
+		"""
+		logger.error(f'Validation failed for {value} in {cls.__name__}.')
+		raise ValidationError(
+			self.error_message,
+			model=cls,
+		)
+
+	def validate(self, cls: Any, value: T) -> T:
+		"""Validate the value.
+
+		If the value is None, that is the fields is optional
+		in the model, then it is returned as is without any validation.
+
+		Args:
+			cls: The class being validated.
+			value: The value of the field being validated.
+
+		Returns:
+			value: The validated value (if valid).
+
+		Raises:
+			ValidationError: If the value is not valid.
+		"""
+		if not value:
+			return value
+		elif not self.validation_logic(value):
+			self._raise_error(cls, value)
+		return value

tesk/api/specs/task_execution_service.117cd92.openapi.yaml

@@ -120,7 +120,7 @@ paths:
             ?tag_key=foo1&tag_value=bar1&tag_key=foo2&tag_value=bar2
           ```
           Should be constructed into the structure { "foo1" : "bar1", "foo2" : "bar2"}
-          
+
           ```
             ?tag_key=foo1
           ```
@@ -884,4 +884,4 @@ components:
             System logs are only included in the FULL task view.
           items:
             type: string
-      description: TaskLog describes logging information related to a Task.
+      description: TaskLog describes logging information related to a Task.