Document modules

- Document all the modules in loader/reducers and handlers packages

Author: pbashyal-nmdp

pyard/ard_refactored.py

@@ -16,8 +16,8 @@
 )
 from .exceptions import InvalidMACError, InvalidTypingError
 from .handlers import (
-    AlleleReducer,
-    GLStringProcessor,
+    AlleleHandler,
+    GLStringHandler,
     MACHandler,
     SerologyHandler,
     V2Handler,
@@ -118,8 +118,8 @@ def _initialize_database(self, imgt_version: str, load_mac: bool):
 
     def _initialize_handlers(self):
         """Initialize all specialized handlers"""
-        self.allele_reducer = AlleleReducer(self)
-        self.gl_processor = GLStringProcessor(self)
+        self.allele_reducer = AlleleHandler(self)
+        self.gl_processor = GLStringHandler(self)
         self.mac_handler = MACHandler(self)
         self.serology_handler = SerologyHandler(self)
         self.v2_handler = V2Handler(self)

pyard/handlers/__init__.py

@@ -1,16 +1,16 @@
 # -*- coding: utf-8 -*-
 
-from .allele_reducer import AlleleReducer
-from .gl_string_processor import GLStringProcessor
+from .allele_handler import AlleleHandler
+from .gl_string_processor import GLStringHandler
 from .mac_handler import MACHandler
 from .serology_handler import SerologyHandler
 from .shortnull_handler import ShortNullHandler
 from .v2_handler import V2Handler
 from .xx_handler import XXHandler
 
 __all__ = [
-    "AlleleReducer",
-    "GLStringProcessor",
+    "AlleleHandler",
+    "GLStringHandler",
     "MACHandler",
     "SerologyHandler",
     "V2Handler",

pyard/handlers/allele_handler.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+
+from typing import TYPE_CHECKING
+
+from ..constants import VALID_REDUCTION_TYPE
+from ..reducers.reducer_factory import StrategyFactory
+
+if TYPE_CHECKING:
+    from ..ard import ARD
+
+
+class AlleleHandler:
+    """Handles core allele reduction logic using Strategy Pattern
+
+    This class serves as the main handler for reducing HLA alleles to different
+    resolution levels (G group, P group, lg, etc.). It uses the Strategy Pattern
+    to delegate the actual reduction logic to specific strategy classes.
+    """
+
+    def __init__(self, ard_instance: "ARD"):
+        """Initialize the AlleleReducer with an ARD instance
+
+        Args:
+            ard_instance: The main ARD object containing database connections
+                         and configuration settings
+        """
+        self.ard = ard_instance
+        # Factory that creates appropriate reduction strategy based on redux_type
+        self.strategy_factory = StrategyFactory(ard_instance)
+
+    def reduce_allele(
+        self, allele: str, redux_type: VALID_REDUCTION_TYPE, re_ping=True
+    ) -> str:
+        """Core allele reduction logic using Strategy Pattern
+
+        Reduces an HLA allele to the specified resolution level by delegating
+        to the appropriate reduction strategy.
+
+        Args:
+            allele: HLA allele string to reduce (e.g., "A*01:01:01:01")
+            redux_type: Type of reduction to perform (G, P, lg, lgx, W, exon, U2, S)
+            re_ping: Whether to re-ping for P groups when G groups are unavailable
+
+        Returns:
+            Reduced allele string according to the specified redux_type
+        """
+        # Get the appropriate reduction strategy for the redux_type
+        strategy = self.strategy_factory.get_strategy(redux_type)
+        # Execute the reduction using the selected strategy
+        return strategy.reduce(allele)
+
+    def add_lg_suffix(self, redux_allele):
+        """Add lg suffix to reduced allele - kept for backward compatibility
+
+        Appends the appropriate suffix ('g' or 'ARS') to reduced alleles.
+        Handles both single alleles and ambiguous allele lists separated by '/'.
+
+        Args:
+            redux_allele: Reduced allele string, may contain multiple alleles
+                         separated by '/'
+
+        Returns:
+            Allele string with appropriate suffix added to each allele
+        """
+        # Handle ambiguous alleles (multiple alleles separated by '/')
+        if "/" in redux_allele:
+            return "/".join(
+                [self.add_lg_suffix(allele) for allele in redux_allele.split("/")]
+            )
+        # Use 'ARS' suffix if configured, otherwise use 'g' suffix
+        if self.ard._config["ARS_as_lg"]:
+            return redux_allele + "ARS"
+        return redux_allele + "g"

pyard/handlers/allele_reducer.py

@@ -10,54 +10,104 @@
     from ..ard import ARD
 
 
-class GLStringProcessor:
-    """Handles GL string parsing, validation and processing"""
+class GLStringHandler:
+    """Handles GL string parsing, validation and processing
+
+    GL (Genotype List) strings represent HLA typing data using standardized
+    delimiters to express ambiguity and relationships between alleles.
+    This class processes these complex strings by parsing delimiters and
+    applying reductions to individual components.
+    """
 
     def __init__(self, ard_instance: "ARD"):
+        """Initialize the GLStringHandler with an ARD instance
+
+        Args:
+            ard_instance: The main ARD object for database access and configuration
+        """
         self.ard = ard_instance
 
     def process_gl_string(
         self, glstring: str, redux_type: VALID_REDUCTION_TYPE = "lgx"
     ) -> str:
-        """Main GL string processing logic extracted from redux method"""
+        """Main GL string processing logic extracted from redux method
+
+        Processes GL strings by parsing delimiters in order of precedence
+        and applying reductions to individual components. GL string delimiters:
+        ^ = unphased genotype list
+        | = phased genotype list
+        + = allele list (multiple alleles at same locus)
+        ~ = possible allele list
+        / = ambiguous allele list
+
+        Args:
+            glstring: GL string to process (e.g., "A*01:01+A*02:01^B*07:02")
+            redux_type: Type of reduction to apply to each component
+
+        Returns:
+            Processed GL string with reductions applied
+        """
         validate_reduction_type(redux_type)
 
+        # Validate GL string structure if strict mode is enabled
         if self.ard._config["strict"]:
             self.validate_gl_string(glstring)
 
-        # Handle GL string delimiters
+        # Handle GL string delimiters in order of precedence
+        # Unphased genotype list (highest precedence)
         if "^" in glstring:
             return self._sorted_unique_gl(
                 [self.ard.redux(a, redux_type) for a in glstring.split("^")], "^"
             )
 
+        # Phased genotype list
         if "|" in glstring:
             return self._sorted_unique_gl(
                 [self.ard.redux(a, redux_type) for a in glstring.split("|")], "|"
             )
 
+        # Allele list (multiple alleles at same locus)
         if "+" in glstring:
             return self._sorted_unique_gl(
                 [self.ard.redux(a, redux_type) for a in glstring.split("+")], "+"
             )
 
+        # Possible allele list
         if "~" in glstring:
             return self._sorted_unique_gl(
                 [self.ard.redux(a, redux_type) for a in glstring.split("~")], "~"
             )
 
+        # Ambiguous allele list (lowest precedence)
         if "/" in glstring:
             return self._sorted_unique_gl(
                 [self.ard.redux(a, redux_type) for a in glstring.split("/")], "/"
             )
 
+        # Single allele - return as-is for further processing
         return glstring
 
     def _sorted_unique_gl(self, gls: List[str], delim: str) -> str:
-        """Make a list of sorted unique GL Strings separated by delim"""
+        """Make a list of sorted unique GL Strings separated by delim
+
+        Creates a sorted, deduplicated list of GL string components.
+        Different delimiters have different sorting behaviors:
+        - '~' preserves original order (no sorting/deduplication)
+        - '+' sorts but keeps structure intact
+        - Others flatten, deduplicate, and sort
+
+        Args:
+            gls: List of GL string components to process
+            delim: Delimiter to use for joining results
+
+        Returns:
+            Sorted and deduplicated GL string components joined by delimiter
+        """
+        # Possible allele list (~) preserves original order
         if delim == "~":
             return delim.join(gls)
 
+        # Allele list (+) sorts but maintains structure
         if delim == "+":
             non_empty_gls = filter(lambda s: s != "", gls)
             return delim.join(
@@ -71,6 +121,7 @@ def _sorted_unique_gl(self, gls: List[str], delim: str) -> str:
                 )
             )
 
+        # Other delimiters: flatten, deduplicate, and sort
         all_gls = []
         for gl in gls:
             all_gls += gl.split(delim)
@@ -87,7 +138,22 @@ def _sorted_unique_gl(self, gls: List[str], delim: str) -> str:
         )
 
     def validate_gl_string(self, glstring: str) -> bool:
-        """Validate GL string structure and components"""
+        """Validate GL string structure and components
+
+        Recursively validates GL string by parsing delimiters and checking
+        that all leaf components (individual alleles) are valid according
+        to the ARD database.
+
+        Args:
+            glstring: GL string to validate
+
+        Returns:
+            True if all components are valid
+
+        Raises:
+            InvalidAlleleError: If any component allele is invalid
+        """
+        # Recursively validate components separated by each delimiter type
         if "^" in glstring:
             return all(map(self.validate_gl_string, glstring.split("^")))
         if "|" in glstring:
@@ -99,7 +165,7 @@ def validate_gl_string(self, glstring: str) -> bool:
         if "/" in glstring:
             return all(map(self.validate_gl_string, glstring.split("/")))
 
-        # what falls through here is an allele
+        # Base case: validate individual allele against database
         is_valid_allele = self.ard._is_valid(glstring)
         if not is_valid_allele:
             from ..exceptions import InvalidAlleleError