feat: add base classes and docs

docs/source/index.rst

@@ -19,7 +19,7 @@ Package contents
 
 .. toctree::
    :maxdepth: 2
-   :caption: package
+   :caption: API referance
 
    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:

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 classes 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/base/__init__.py

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

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

@@ -0,0 +1,79 @@
+"""Base validator class, all custom validator 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 server 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__':

tesk/tesk_app.py

@@ -0,0 +1,91 @@
+"""Base class for the APP used in initialization of API."""
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional, final
+
+from foca import Foca
+from foca.config.config_parser import ConfigParser
+
+logger = logging.getLogger(__name__)
+
+
+class TeskApp(Foca):
+	"""TESK API class extending the Foca framework."""
+
+	def __init__(
+		self,
+		config_file: Optional[Path] = None,
+		custom_config_model: Optional[Path] = None,
+	) -> None:
+		"""Initialize the TeskApp class.
+
+		Args:
+			config_file (Optional[Path]): Path to the configuration file.
+				Defaults to None.
+			custom_config_model (Optional[Path]): Path to the custom
+				configuration model file. Defaults to None.
+		"""
+		if not config_file:
+			self._load_config_file()
+		else:
+			self.config_file = config_file
+		if not custom_config_model:
+			self.custom_config_model = self._load_custom_config_model()
+		else:
+			self.custom_config_model = custom_config_model
+		self.conf = ConfigParser(
+			config_file=self.config_file,
+			custom_config_model=self.custom_config_model,
+			format_logs=True,
+		).config
+		self._app = self.create_app()
+
+	@final
+	def run(self) -> None:
+		"""Run the application."""
+		_environment = self.conf.server.environment or 'production'
+		logger.info(f'Running application in {_environment} environment...')
+		_debug = self.conf.server.debug or False
+		self._app.run(
+			host=self.conf.server.host, port=self.conf.server.port, debug=_debug
+		)
+
+	@final
+	def _load_config_file(self) -> None:
+		"""Load the configuration file path from env variable or default location.
+
+		Raises:
+			FileNotFoundError: If the configuration file is not found.
+		"""
+		logger.info('Loading configuration path...')
+		if config_path_env := os.getenv('TESK_FOCA_CONFIG_FILE'):
+			self.config_file = Path(config_path_env).resolve()
+		else:
+			self.config_file = (
+				Path(__file__).parents[1] / 'deployment' / 'config.yaml'
+			).resolve()
+
+		if not self.config_file.exists():
+			raise FileNotFoundError(
+				f'Config file not found at: {self.config_file}',
+			)
+
+	@final
+	def _load_custom_config_model(self) -> None:
+		"""Load the custom configuration model path from environment variable or None.
+
+		Raises:
+			FileNotFoundError: If the custom configuration model is specified and found.
+		"""
+		logger.info('Loading custom configuration model path...')
+		if custom_config_model_env := os.getenv('TESK_FOCA_CUSTOM_CONFIG_MODEL'):
+			self.custom_config_model = Path(custom_config_model_env).resolve()
+		else:
+			self.custom_config_model = None
+
+		if self.custom_config_model and not self.custom_config_model.exists():
+			raise FileNotFoundError(
+				f'Custom configuration model not found at: {self.custom_config_model}',
+			)