tol-sdk 1.7.4__py3-none-any.whl → 1.7.5b2__py3-none-any.whl

tol/validators/ena_submittable.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from tol.core import DataObject, DataSource
+from tol.core.validate import Validator
+from tol.sources.ena import ena
+
+
+class EnaSubmittableValidator(Validator):
+    """
+    Validates that a stream of `DataObject` instances
+    contains field that is part of a list.
+    """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        field_name: str
+
+    __slots__ = ['__config', '__ena_datasource', '__cached_species']
+    __config: Config
+    __ena_datasource: DataSource
+    __cached_species: Dict[str, Any]
+
+    def __init__(
+        self,
+        config: Config,
+        ena_datasource: DataSource | None = ena(),  # For testing
+    ) -> None:
+
+        super().__init__()
+
+        self.__config = config
+        self.__ena_datasource = ena_datasource
+        self.__cached_species = {}
+
+    def _validate_data_object(
+        self,
+        obj: DataObject
+    ) -> None:
+        taxon_id = obj.get_field_by_name(self.__config.field_name)
+        if taxon_id not in self.__cached_species:
+            ena_taxon = self.__ena_datasource.get_one('submittable_taxon', taxon_id)
+            if ena_taxon:
+                self.__cached_species[taxon_id] = ena_taxon
+        if taxon_id not in self.__cached_species:
+            self.add_error(
+                object_id=obj.id,
+                detail=f'Field {self.__config.field_name} value '
+                       f'"{taxon_id}" not found in ENA',
+                field=self.__config.field_name,
+            )
+        elif not self.__cached_species[taxon_id].submittable:
+            self.add_error(
+                object_id=obj.id,
+                detail=f'Field {self.__config.field_name} value '
+                       f'"{taxon_id}" is not submittable in ENA',
+                field=self.__config.field_name,
+            )

tol/validators/interfaces/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from .condition_evaluator import Condition, ConditionDict, ConditionEvaluator  # noqa

tol/validators/interfaces/condition_evaluator.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from abc import ABC
+from dataclasses import dataclass
+from typing import Any, Dict, Tuple, cast
+
+from tol.core import DataObject
+
+
+ConditionDict = Dict[str, str | Any | bool]
+"""
+The dict representation of a Condition. Conditions can be constructed
+from such a dict through Condition.from_dict(condition_dict)
+"""
+
+
+@dataclass(slots=True)
+class Condition:
+    field: str
+    operator: str
+    value: Any
+    # If this condition fails, should it be an error or a warning?
+    # The reporting of this error or warning is done in the calling validator
+    is_error: bool = True
+
+    def __repr__(self) -> str:
+        return f'{self.field} {self.operator} {self.value}'
+
+    @staticmethod
+    def from_dict(condition_dict: ConditionDict) -> 'Condition':
+        """
+        A means of instantiating a Condition from a dictionary.
+        This is a separate method (rather than constructing with kwargs
+        like `Condition(**condition_dict))`) to allow for both precense
+        and type checking for each field.
+        """
+        try:
+            # Extract fields
+            field = condition_dict['field']
+            operator = condition_dict['operator']
+            value = condition_dict['value']
+            is_error = condition_dict.get('is_error', True)
+
+            # Ensure fields are the correct type
+            if not isinstance(field, str) and not isinstance(operator, str):
+                raise Exception(
+                    f'Dictionary {condition_dict} not in valid format '
+                    f'to convert to Condition (type of condition dict incorrect)'
+                )
+
+            return Condition(
+                cast(str, field),
+                cast(str, operator),
+                value,
+                cast(bool, is_error),
+            )
+        except IndexError as e:
+            raise Exception(
+                f'Dictionary {condition_dict} not in valid format '
+                f'to convert to Condition (key "{e.args[0]}" not found)'
+            )
+
+
+class ConditionEvaluator(ABC):
+    """
+    Interface to be inherited by validators. Evaluates the provided condition given its
+    operator and operands
+    """
+    def _evaluate_condition(self, condition: Condition, obj: DataObject) -> Tuple[bool, Any]:
+        """
+        Evaluates the provided condition given its operator and operands.
+        If `operator` is not one of the supported operators, an exception is thrown.
+        """
+        value_to_test = obj.get_field_by_name(condition.field)
+
+        match condition.operator:
+            case '==':
+                return (value_to_test == condition.value, value_to_test)
+            case '!=':
+                return (value_to_test != condition.value, value_to_test)
+            case '<':
+                return (value_to_test < condition.value, value_to_test)
+            case '<=':
+                return (value_to_test <= condition.value, value_to_test)
+            case '>':
+                return (value_to_test > condition.value, value_to_test)
+            case '>=':
+                return (value_to_test >= condition.value, value_to_test)
+            case 'in':
+                return (value_to_test in condition.value, value_to_test)
+            case _:
+                raise Exception(f'VALIDATOR SETUP ERROR: `{condition.operator}` is not '
+                                f'a supported operator for {type(self).__name__}')
+
+    def _does_condition_pass(self, condition: Condition, obj: DataObject) -> bool:
+        """
+        Helper function for when you only want to know whether the condition passes,
+        and don't need the actual value
+        """
+        return self._evaluate_condition(condition, obj)[0]

tol/validators/min_one_valid_value.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from dataclasses import dataclass
+
+from tol.core import DataObject
+from tol.core.validate import Validator
+
+
+class MinOneValidValueValidator(Validator):
+    """
+    Validates that a stream of `DataObject` instances
+    have at least one valid value present in a list of specified keys.
+    """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        non_valid_values: list[str]
+        keys: list[str]
+
+    __slots__ = ['__config']
+    __config: Config
+
+    def __init__(
+        self,
+        config: Config,
+    ) -> None:
+
+        super().__init__()
+        self.__config = config
+
+    def _validate_data_object(
+        self,
+        obj: DataObject
+    ) -> None:
+
+        found_valid_value = False
+
+        for key in self.__config.keys:
+            value = obj.attributes[key]
+
+            if value is not None and value not in self.__config.non_valid_values:
+                found_valid_value = True
+                break
+
+        if not found_valid_value:
+            self.add_error(
+                object_id=obj.id,
+                detail=(
+                    f'At least one of: {self.__config.keys} '
+                    'must not be: ' + ', '.join(self.__config.non_valid_values)
+                    + ' or empty.'
+                ),
+                field=', '.join(self.__config.keys),
+            )

tol/validators/mutually_exclusive.py

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from dataclasses import dataclass
+from typing import Any, List
+
+from tol.core import DataObject, Validator
+
+from .interfaces import Condition, ConditionDict, ConditionEvaluator
+
+
+class MutuallyExclusiveValidator(Validator, ConditionEvaluator):
+    """
+    Validates an incoming stream of `DataObject` instances,
+    where the resultant field from field_one_condition must not
+    have the same values for target_fields as the resultant
+    field from field_two_condition
+    """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        first_field_where: ConditionDict
+        second_field_where: ConditionDict
+        target_fields: List[str]
+        detail: str | None = None
+
+        def _get_error_message(self) -> str:
+            # Extract conditions
+            first_condition = Condition.from_dict(self.first_field_where)
+            second_condition = Condition.from_dict(self.second_field_where)
+
+            # Use a pre-defined, hard-coded detail message if one was not provided
+            if self.detail is None:
+                multiple_target_fields = len(self.target_fields) > 1
+                possible_plural = 's' if multiple_target_fields else ''
+
+                target_fields_str = ''
+                if multiple_target_fields:
+                    for index, field in enumerate(self.target_fields):
+                        if index == 0:
+                            # First field in the list
+                            target_fields_str += f'{field}'
+                        elif index == len(self.target_fields) - 1:
+                            # Last field in the list
+                            target_fields_str += f' and {field}'
+                        else:
+                            # Middle fields
+                            target_fields_str += f', {field}'
+                else:  # Only one field
+                    target_fields_str = self.target_fields[0]
+
+                return (
+                    f'The field{possible_plural} {target_fields_str} cannot have the same '
+                    f'value{possible_plural} both when {first_condition} and when '
+                    f'{second_condition}'
+                )
+            else:
+                return self.detail
+
+    __slots__ = ['__config', '__first_list', '__second_list']
+    __config: Config
+    __first_list: List[Any]
+    __second_list: List[Any]
+
+    def __init__(self, config: Config) -> None:
+        super().__init__()
+
+        self.__config = config
+        self.__first_list = []
+        self.__second_list = []
+
+    def _validate_data_object(self, obj: DataObject) -> None:
+        # Check first field
+        if self._does_condition_pass(Condition.from_dict(self.__config.first_field_where), obj):
+            # Check whether the values of the target fields were found in the second list
+            if [
+                obj.get_field_by_name(target_field)
+                for target_field in self.__config.target_fields
+            ] in self.__second_list:
+                self.add_error(
+                    object_id=obj.id,
+                    detail=self.__config._get_error_message()
+                )
+
+            # Add the values of the target fields to the first list
+            self.__first_list.append(
+                [
+                    obj.get_field_by_name(target_field)
+                    for target_field in self.__config.target_fields
+                ]
+            )
+        # Check second field (same as the first condition, but for the second!)
+        elif self._does_condition_pass(Condition.from_dict(self.__config.second_field_where), obj):
+            # Check whether the values of the target fields were found in the first list
+            if [
+                obj.get_field_by_name(target_field)
+                for target_field in self.__config.target_fields
+            ] in self.__first_list:
+                self.add_error(
+                    object_id=obj.id,
+                    detail=self.__config._get_error_message()
+                )
+
+            # Add the values of the target fields to the second list
+            self.__second_list.append(
+                [
+                    obj.get_field_by_name(target_field)
+                    for target_field in self.__config.target_fields
+                ]
+            )
+        # If neither condition passes, the data object must be valid (for this validator anyway!)

tol/validators/regex.py

@@ -4,12 +4,18 @@
 
 import re
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, List
 
 from tol.core import DataObject
 from tol.core.validate import Validator
 
 
+RegexDict = dict[
+    str,
+    str | bool | list[Any],
+]
+
+
 @dataclass(frozen=True, kw_only=True)
 class Regex:
     key: str
@@ -23,23 +29,22 @@ class Regex:
         return re.search(self.regex, str(__v or ''))
 
 
-RegexDict = dict[
-    str,
-    str | bool | list[Any],
-]
-"""Can also specify `Regex` as a `dict`"""
-
-
 class RegexValidator(Validator):
     """
     Validates an incoming stream of `DataObject` instances
     according to the specified allowed values for a given
     key.
     """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        regexes: List[Regex | RegexDict]
+
+    __slots__ = ['__config']
+    __config: Config
 
     def __init__(
         self,
-        config: list[Regex | RegexDict]
+        config: Config
     ) -> None:
 
         super().__init__()
@@ -54,19 +59,6 @@ class RegexValidator(Validator):
         for k, v in obj.attributes.items():
             self.__validate_attribute(obj, k, v)
 
-    def __get_config(
-        self,
-        config: list[Regex | RegexDict],
-    ) -> list[Regex]:
-
-        # Ensure config is in Regex format
-        # (as you can either pass in a list of Regex or a RegexDict,
-        # which can be used to initialize a Regex)
-        return [
-            c if isinstance(c, Regex) else Regex(**c)
-            for c in config
-        ]
-
     def __validate_attribute(
         self,
         obj: DataObject,
@@ -85,7 +77,7 @@ class RegexValidator(Validator):
         key: str,
     ) -> list[Regex]:
         return [
-            a for a in self.__config
+            a for a in self.__config.regexes
             if a.key == key
         ]
 
@@ -107,3 +99,18 @@ class RegexValidator(Validator):
                 detail=c.detail,
                 field=c.key,
             )
+
+    def __get_config(
+        self,
+        config: Config,
+    ) -> Config:
+
+        # Ensure config is in Regex format
+        # (as you can either pass in a list of Regex or a RegexDict,
+        # which can be used to initialize a Regex)
+        return self.Config(
+            regexes=[
+                c if isinstance(c, Regex) else Regex(**c)
+                for c in config.regexes
+            ]
+        )

tol/validators/regex_by_value.py

@@ -2,20 +2,13 @@
 #
 # SPDX-License-Identifier: MIT
 
-from typing import Any
+from dataclasses import dataclass
+from typing import Dict, List
 
 from tol.core import DataObject
 from tol.core.validate import Validator
 
-from .regex import Regex
-
-RegexDict = dict[
-    str,
-    str | bool | list[Any],
-]
-Config = dict[str, str | dict[str, list[Regex | RegexDict]]]
-
-"""Can also specify `Regex` as a `dict`"""
+from .regex import Regex, RegexDict
 
 
 class RegexByValueValidator(Validator):
@@ -24,46 +17,34 @@ class RegexByValueValidator(Validator):
     according to the specified allowed values for a given
     key.
     """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        key_column: str
+        regexes: Dict[str, List[Regex | RegexDict]]
+
+    __slots__ = ['__config']
+    config: Config
 
     def __init__(
         self,
-        config: dict[str, str | list[str]]
+        config: Config
     ) -> None:
 
         super().__init__()
 
         self.__config = self.__get_config(config)
 
-    def __get_config(
-        self,
-        config: Config,
-    ) -> Config:
-
-        return {
-            'key_column': config['key_column'],
-            'regexes': {
-                k: [
-                    # Ensure they're all in Regex format
-                    # (as you can either pass in a list of Regex or a RegexDict,
-                    # which can be used to initialize a Regex)
-                    c if isinstance(c, Regex) else Regex(**c)
-                    for c in v
-                ]
-                for k, v in config['regexes'].items()
-            }
-        }
-
     def _validate_data_object(
         self,
         obj: DataObject
     ) -> None:
         # Pull out value of the 'key_column' attribute
-        key_column_value = obj.attributes.get(self.__config['key_column'])
+        key_column_value = obj.attributes.get(self.__config.key_column)
         if not key_column_value:
             return
 
         # Pull out relevant regex list based on this value: {[{'name': 'regex'}]}
-        regex_list = self.__config['regexes'].get(key_column_value)
+        regex_list = self.__config.regexes.get(key_column_value)
         if not regex_list:
             return
         self.__validate_attribute(obj, regex_list)
@@ -71,7 +52,7 @@ class RegexByValueValidator(Validator):
     def __validate_attribute(
         self,
         obj: DataObject,
-        regexes: list[Regex],
+        regexes: List[Regex],
     ) -> None:
         for r in regexes:
             attribute_name = r.key
@@ -97,3 +78,22 @@ class RegexByValueValidator(Validator):
                 detail=c.detail,
                 field=c.key,
             )
+
+    def __get_config(
+        self,
+        config: Config,
+    ) -> Config:
+
+        # Ensure config is in Regex format
+        # (as you can either pass in a list of Regex or a RegexDict,
+        # which can be used to initialize a Regex)
+        return self.Config(
+            key_column=config.key_column,
+            regexes={
+                k: [
+                    c if isinstance(c, Regex) else Regex(**c)
+                    for c in v
+                ]
+                for k, v in config.regexes.items()
+            }
+        )

tol/validators/specimens_have_same_taxon.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from dataclasses import dataclass
+from typing import Dict
+
+from tol.core import Validator
+from tol.core.data_object import DataObject
+
+
+class SpecimensHaveSameTaxonValidator(Validator):
+    """
+    Validates an incoming stream of `DataObject` instances.
+    For each data object (sample) not a SYMBIONT, it checks that
+    there are no samples with SPECIMEN_ID which has different TAXON_ID
+    """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        taxon_id_field: str
+        symbiont_field: str
+        specimen_id_field: str
+
+    __slots__ = ['__config', '__seen']
+    __config: Config
+    __seen: Dict[str, str]
+
+    def __init__(self, config: Config) -> None:
+        super().__init__()
+        self.__seen = {}
+        self.__config = config
+
+    def _validate_data_object(self, obj: DataObject) -> None:
+        # Explaining the code concept using a standard example
+        # seen{}
+        # 1st Pass=>    element['specimen_id']  =   A
+        #               element['taxon_id']     =   AA
+        #               seen{ A:AA }
+        # 2nd pass=>    element['specimen_id']  =   A
+        #               element['taxon_id']     =   AB
+        #               AB != AA
+        #               Flag error
+        # From Nithin :)
+
+        # Ensure the data object is not a SYMBIONT
+        if obj.attributes.get(self.__config.symbiont_field) != 'SYMBIONT':
+            specimen_id = obj.attributes.get(self.__config.specimen_id_field)
+            if specimen_id is None:
+                return
+            taxon_id = obj.attributes.get(self.__config.taxon_id_field)
+            if taxon_id is None:
+                return
+            if specimen_id in self.__seen and taxon_id != self.__seen[specimen_id]:
+                self.add_error(
+                    object_id=obj.id,
+                    detail='A non-symbiont must have a matching Specimen ID and Taxon ID',
+                    field=self.__config.specimen_id_field,
+                )
+            if specimen_id not in self.__seen:
+                self.__seen[specimen_id] = taxon_id

tol/validators/sts_fields.py

@@ -0,0 +1,88 @@
+# SPDX-FileCopyrightText: 2025 Genome Research Ltd.
+#
+# SPDX-License-Identifier: MIT
+
+from dataclasses import dataclass
+from typing import List
+
+from tol.core import DataObject, DataSource
+from tol.core.validate import Validator
+from tol.sources.sts import sts
+
+
+class StsFieldsValidator(Validator):
+    """
+    Validates that a stream of `DataObject` instances
+    contains fields that observe the validations in STS
+    """
+    @dataclass(slots=True, frozen=True, kw_only=True)
+    class Config:
+        project_code: str
+
+    __slots__ = ['__config', '__datasource', '__fields']
+    __config: Config
+    __datasource: DataSource
+    __fields: List[str | int | float]
+
+    def __init__(
+        self,
+        config: Config,
+        datasource: DataSource = sts(),  # For testing
+    ) -> None:
+
+        super().__init__()
+
+        self.__config = config
+        self.__datasource = datasource
+        self.__fields = self.__initialize_fields_from_datasource()
+
+    def __initialize_fields_from_datasource(self) -> List[str | int | float]:
+        return {
+            field.get('data_input_key'): field
+            for field in self.__datasource.get_one(
+                'project', self.__config.project_code
+            ).template.get('data_fields', [])
+            if field.get('in_manifest')
+        }
+
+    def _validate_data_object(
+        self,
+        obj: DataObject
+    ) -> None:
+        for field in self.__fields.values():
+            # Get the value from the data object
+            field_value = obj.get_field_by_name(field.get('data_input_key'))
+            if field.get('mandatory_input') and (field_value is None or field_value == ''):
+                self.add_error(
+                    object_id=obj.id,
+                    detail=f'Field {field.get("data_input_key")} is required '
+                           f'for project {self.__config.project_code}',
+                    field=field.get('data_input_key'),
+                )
+            elif field.get('allowed_values') and field_value not in field.get('allowed_values'):
+                self.add_error(
+                    object_id=obj.id,
+                    detail=f'Field {field.get("data_input_key")} value '
+                           f'"{field_value}" not found in allowed values '
+                           f'{field.get("allowed_values")} for project '
+                           f'{self.__config.project_code}',
+                    field=field.get('data_input_key'),
+                )
+            elif field.get('min') and field_value < field.get('min'):
+                self.add_error(
+                    object_id=obj.id,
+                    detail=f'Field {field.get("data_input_key")} value '
+                           f'"{field_value}" is less than minimum value '
+                           f'"{field.get("min")}" for project '
+                           f'{self.__config.project_code}',
+                    field=field.get('data_input_key'),
+                )
+            elif field.get('max') and field_value > field.get('max'):
+                self.add_error(
+                    object_id=obj.id,
+                    detail=f'Field {field.get("data_input_key")} value '
+                           f'"{field_value}" is greater than maximum value '
+                           f'"{field.get("max")}" for project '
+                           f'{self.__config.project_code}',
+                    field=field.get('data_input_key'),
+                )