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/

docs/source/index.rst

@@ -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:

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

@@ -68,6 +68,7 @@ types-botocore = "^1.0.2"
 types-requests = "^2.31.0.20240406"
 types-urllib3 = "^1.26.25.14"
 types-werkzeug = "^1.0.9"
+types-pyyaml = "^6.0.12.20240311"
 
 [tool.poetry.scripts]
 api = 'tesk.app:main'

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,46 @@
+"""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.
+	"""
+
+	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.
+		"""
+		pass
+
+	@final
+	def response(self) -> dict[Any, 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.
+
+	Validators assume that the filed being validated is not optional as
+	optional fields are handled by the Pydantic model itself and mypy type
+	checking.
+	"""
+
+	@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, v: T) -> bool:
+		"""Validation logic for the field.
+
+		Args:
+			v: The value being validated.
+
+		Returns:
+			bool: True if the validation is successful, False otherwise.
+		"""
+		pass
+
+	def _raise_error(self, cls: Any, v: T) -> None:
+		"""Raise a validation error.
+
+		Args:
+			cls: The class being validated.
+			v: The value being validated.
+
+		Raises:
+			ValidationError: Raised when the validation fails.
+		"""
+		logger.error(f'Validation failed for {v} in {cls.__name__}.')
+		raise ValidationError(
+			self.error_message,
+			model=cls,
+		)
+
+	def validate(self, cls: Any, v: T) -> T:
+		"""Validate the value.
+
+		If the value is None, ie the fields is optional
+		in the model, then it is returned as is without any validation.
+
+		Args:
+			cls: The class being validated.
+			v: The value being validated.
+
+		Returns:
+			T: The validated value (if valid).
+
+		Raises:
+			ValidationError: If the value is not valid.
+		"""
+		if not v:
+			return v
+		elif not self.validation_logic(v):
+			self._raise_error(cls, v)
+		return v

tesk/app.py

@@ -1,52 +1,19 @@
-"""API server entry point."""
+"""App entry point."""
 
 import logging
-import os
-from pathlib import Path
 
-from connexion import FlaskApp
-from foca import Foca
+from tesk.tesk_app import TeskApp
 
 logger = logging.getLogger(__name__)
 
 
-def init_app() -> FlaskApp:
-	"""Initialize and return the FOCA app.
-
-	This function initializes the FOCA app by loading the configuration
-	from the environment variable `TESK_FOCA_CONFIG_PATH` if set, or from
-	the default path if not. It raises a `FileNotFoundError` if the
-	configuration file is not found.
-
-	Returns:
-			FlaskApp: A Connexion application instance.
-
-	Raises:
-			FileNotFoundError: If the configuration file is not found.
-	"""
-	# Determine the configuration path
-	config_path_env = os.getenv('TESK_FOCA_CONFIG_PATH')
-	if config_path_env:
-		config_path = Path(config_path_env).resolve()
-	else:
-		config_path = (
-			Path(__file__).parents[1] / 'deployment' / 'config.yaml'
-		).resolve()
-
-	# Check if the configuration file exists
-	if not config_path.exists():
-		raise FileNotFoundError(f'Config file not found at: {config_path}')
-
-	foca = Foca(
-		config_file=config_path,
-	)
-	return foca.create_app()
-
-
 def main() -> None:
 	"""Run FOCA application."""
-	app = init_app()
-	app.run(port=app.port)
+	try:
+		TeskApp().run()
+	except Exception:
+		logger.exception('An error occurred while running the application.')
+		raise
 
 
 if __name__ == '__main__':