labfreed 0.0.4__py3-none-any.whl → 0.2.0b0__py3-none-any.whl

labfreed/PAC_CAT/__init__.py

@@ -1 +1,17 @@
+from .pac_cat import PAC_CAT
+from .category_base import Category
+from .predefined_categories import Material_Device, Material_Substance, Material_Consumable, Material_Misc, Data_Method, Data_Result, Data_Progress, Data_Calibration, Data_Abstract
 
+__all__ = [
+    "PAC_CAT",
+    "Category",
+    "Material_Device",
+    "Material_Substance",
+    "Material_Consumable",
+    "Material_Misc",
+    "Data_Method",
+    "Data_Result",
+    "Data_Progress",
+    "Data_Calibration",
+    "Data_Abstract"
+]

labfreed/PAC_CAT/category_base.py

@@ -0,0 +1,51 @@
+               
+from typing import Any
+from pydantic import PrivateAttr, computed_field, model_validator
+from labfreed.labfreed_infrastructure import LabFREED_BaseModel, ValidationMsgLevel
+from labfreed.pac_id.id_segment import IDSegment
+
+
+class Category(LabFREED_BaseModel):
+    '''
+    Represents a category. \n
+    This is the base class for categories. If possible a more specific category should be used.
+    '''    
+    key:str
+    '''The category key, e.g. "-MD"'''
+    _segments: list[IDSegment] = PrivateAttr(default_factory=list)
+    
+        
+    @computed_field
+    @property
+    def segments(self) -> list[IDSegment]:
+        return self._segments
+    
+    def __init__(self, **data: Any):
+        '''@private'''
+        # Pop the user-provided value for computed segments
+        input_segments = data.pop("segments", None)
+        super().__init__(**data)
+        self._segments = input_segments
+    
+    @model_validator(mode='after')
+    def _warn_unusual_category_key(self):
+        ''' this base class is instantiated only if the key is not a known category key'''
+        if type(self) is Category:
+            self._add_validation_message(
+                        source=f"Category {self.key}",
+                        level = ValidationMsgLevel.RECOMMENDATION,
+                        msg=f'Category key {self.key} is not a well known key. It is recommended to use well known keys only',
+                        highlight_pattern = f"{self.key}"
+            )
+        return self
+    
+    
+    def __str__(self):
+        s = '\n'.join( [f'{field_name} \t ({field_info.alias or ''}): \t {getattr(self, field_name)}' for  field_name, field_info in self.model_fields.items() if getattr(self, field_name)]) 
+        return s 
+
+
+
+
+
+

labfreed/PAC_CAT/pac_cat.py

@@ -0,0 +1,159 @@
+from __future__ import annotations  # optional in 3.11, but recommended for consistency
+
+from typing import Self
+from pydantic import computed_field, model_validator
+
+from rich import print
+from rich.text import Text
+from rich.table import Table
+
+from labfreed.labfreed_infrastructure import ValidationMsgLevel
+
+from labfreed.pac_cat.category_base import Category
+from labfreed.pac_cat.predefined_categories import Data_Calibration, Data_Method, Data_Progress, Data_Result, Material_Consumable, Material_Device, Material_Misc, Material_Substance, Data_Static
+from labfreed.pac_id.id_segment import IDSegment
+from labfreed.pac_id.pac_id import PAC_ID
+
+''' Configure pdoc'''
+
+    
+class PAC_CAT(PAC_ID):
+    ''' 
+    Extends a PAC-ID with interpretation of the identifier as categories
+    '''
+    @computed_field
+    @property
+    def categories(self) -> list[Category]: 
+        '''The categories present in the PAC-ID's identifier'''
+        category_segments = self._split_segments_by_category(self.identifier)
+        categories = list()
+        for c in category_segments:
+            categories.append(self._cat_from_cat_segments(c))
+        return categories
+    
+    
+
+    def get_category(self, key) -> Category:
+        """Helper to get a category by key
+        """ 
+        tmp = [c for c in self.categories if c.key == key]
+        if not tmp:
+            return None
+        return tmp[0]
+    
+    
+    @classmethod
+    def from_categories(cls, issuer:str, categories:list[Category]) -> PAC_CAT:
+        identifier = list()
+        for category in categories:
+            identifier.append(IDSegment(value=category.key))
+            identifier.extend(category.segments)
+        return PAC_CAT(issuer=issuer, identifier=identifier)
+    
+    
+    @classmethod
+    def from_pac_id(cls, pac_id:PAC_ID) -> Self:
+        '''Constructs a PAC-CAT from a PAC-ID'''
+        return PAC_CAT(issuer=pac_id.issuer, identifier=pac_id.identifier)
+    
+
+    
+    def to_pac_id(self) -> PAC_ID:
+        return PAC_ID(issuer=self.issuer, identifier=self.identifier)
+        
+            
+    @classmethod
+    def _cat_from_cat_segments(cls, segments:list[IDSegment]) -> Category:
+        segments = segments.copy()
+        category_key = segments[0].value         
+        segments.pop(0)
+        
+        mapping  = {
+                '-MD': Material_Device,
+                '-MS': Material_Substance,
+                '-MC': Material_Consumable,
+                '-MM': Material_Misc,
+                '-DM': Data_Method,
+                '-DR': Data_Result,
+                '-DC': Data_Calibration,
+                '-DP': Data_Progress,
+                '-DS': Data_Static 
+        }
+        known_cat = mapping.get(category_key)
+        
+        if not known_cat:
+            return Category(key=category_key, segments=segments)
+
+        # implicit segment keys
+        model_dict = {v.alias: None for k, v in known_cat.model_fields.items() if v.alias and k not in ['key','additional_segments']}
+        for k, seg in zip(model_dict.keys(), segments.copy()):
+            if seg.key:
+                break
+            model_dict[k] = seg.value
+            segments.pop(0)
+            
+        # try to fill model keys if not already set
+        for s in segments.copy():
+            if s.key in model_dict.keys() and not model_dict.get(s.key):
+                model_dict[s.key] = s.value
+                segments.remove(s)
+            
+        model_dict['additional_segments'] = segments
+        model_dict['key'] = category_key
+        cat= known_cat(**model_dict)
+        return cat
+    
+    @staticmethod
+    def _split_segments_by_category(segments:list[IDSegment]) -> list[list[IDSegment]]:
+        category_segments = list()
+        c = list()
+        for s in segments:
+            # new category starts with "-"
+            if s.value[0] == '-':
+                c = [s]
+                category_segments.append(c)
+            else:
+                c.append(s)
+                
+        # first cat can be empty > remove
+        category_segments = [c for c in category_segments if len(c) > 0]
+                            
+        return category_segments
+    
+    
+    @model_validator(mode='after')
+    def _check_keys_are_unique_in_each_category(self) -> Self:
+        for c in self.categories:
+            keys = [s.key for s in c.segments if s.key]
+            duplicate_keys = [k for k in set(keys) if keys.count(k) > 1]
+            if duplicate_keys:
+                for k in duplicate_keys:
+                    self._add_validation_message(
+                        source=f"identifier {k}",
+                        level = ValidationMsgLevel.ERROR,
+                        msg=f"Duplicate key {k} in category {c.key}",
+                        highlight_pattern = k
+                    )
+            return self
+        
+    def print_categories(self):
+        table = Table(title=f'Categories in {str(self)}', show_header=False)
+        table.add_column('0')
+        table.add_column('1')
+        for i, c in enumerate(self.categories):
+            if i == 0:
+                title = Text('Main Category', style='bold')
+            else:
+                title = Text('Category', style='bold')
+            
+            table.add_row(title)
+            
+            for field_name, field_info in c.model_fields.items():
+                if not getattr(c, field_name):
+                    continue
+                table.add_row(f"{field_name} ({field_info.alias or ''})",
+                              f" {getattr(c, field_name)}"
+                              )      
+            table.add_section()        
+        print(table)
+        

labfreed/PAC_CAT/predefined_categories.py

@@ -0,0 +1,190 @@
+## Materials
+from abc import ABC
+from pydantic import Field, computed_field, model_validator
+
+from labfreed.labfreed_infrastructure import ValidationMsgLevel
+from labfreed.pac_cat.category_base import Category
+from labfreed.pac_id.id_segment import IDSegment
+
+class PredefinedCategory(Category, ABC):
+    '''@private 
+    Base for Predefined catergories
+    '''
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    @computed_field
+    @property
+    def segments(self) -> list[IDSegment]:
+        return self._get_segments(use_short_notation=False)
+    
+    def _get_segments(self, use_short_notation=False) -> list[IDSegment]:
+        segments = []
+        can_omit_keys = use_short_notation # keeps track of whether keys can still be omitted. That is the case when the segment recommendation is followed
+        for field_name, field_info in self.model_fields.items():
+            if field_name in ['key', 'additional_segments']:
+                continue
+            if value := getattr(self, field_name):
+                if can_omit_keys:
+                    key = None
+                else:
+                    key = field_info.alias
+                segments.append(IDSegment(key= key, value= value)  )
+            else:
+                can_omit_keys = False
+        if self.additional_segments:
+            segments.extend(self.additional_segments)
+        return segments
+    
+    model_config = {
+        "populate_by_name": True 
+    }
+    ''' @private Pydantic tweak to allows model fields to be populated using their Python name, even if they have an alias defined. 
+        The alias we need to use the GS1 code in serialization
+    '''
+
+
+
+class Material_Device(PredefinedCategory):
+    '''Represents the -MD category'''
+    key: str =         Field(default='-MD', frozen=True)
+    model_number: str|None =         Field(              alias='240')
+    serial_number: str|None =        Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    @model_validator(mode='after')
+    def _validate_mandatory_fields(self):
+        if not self.model_number:
+            self._add_validation_message(
+                    source=f"Category {self.key}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f'Category key {self.key} is missing mandatory field Model Number',
+                    highlight_pattern = f"{self.key}"
+            )
+        if not self.serial_number:
+            self._add_validation_message(
+                    source=f"Category {self.key}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f'Category key {self.key} is missing mandatory field Serial Number',
+                    highlight_pattern = f"{self.key}"
+            )
+        return self
+    
+class Material_Substance(PredefinedCategory):
+    '''Represents the -MS category'''
+    key: str =         Field(default='-MS', frozen=True)
+    product_number:str|None =    Field(              alias='240')
+    batch_number:str|None =     Field(default=None, alias='10')
+    container_size:str|None =   Field(default=None, alias='20')
+    container_number:str|None = Field(default=None, alias='21')
+    aliquot:str|None =          Field(default=None, alias='250')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    @model_validator(mode='after')
+    def _validate_mandatory_fields(self):
+        if not self.product_number:
+            self._add_validation_message(
+                    source=f"Category {self.key}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f'Category key {self.key} is missing mandatory field Product Number',
+                    highlight_pattern = f"{self.key}"
+            )
+        return self
+    
+class Material_Consumable(PredefinedCategory):
+    '''Represents the -MC category'''
+    key: str = Field(default='-MC', frozen=True)
+    product_number:str|None =   Field(              alias='240')
+    batch_number:str|None =     Field(default=None, alias='10')
+    packaging_size:str|None =     Field(default=None, alias='20')
+    serial_number:str|None =    Field(default=None, alias='21')
+    aliquot:str|None =          Field(default=None, alias='250')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    @model_validator(mode='after')
+    def _validate_mandatory_fields(self):
+        if not self.product_number:
+            self._add_validation_message(
+                    source=f"Category {self.key}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f"Category key {self.key} is missing mandatory field 'Product Number'",
+                    highlight_pattern = f"{self.key}"
+            )
+        return self
+    
+class Material_Misc(Material_Consumable):
+    '''Represents the -MC category'''
+    # same fields as Consumable
+    key: str = Field(default='-MM', frozen=True)
+    product_number:str|None =   Field(              alias='240')
+    batch_number:str|None =     Field(default=None, alias='10')
+    packaging_size:str|None =     Field(default=None, alias='20')
+    serial_number:str|None =    Field(default=None, alias='21')
+    aliquot:str|None =          Field(default=None, alias='250')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+
+
+## Data
+class Data_Abstract(PredefinedCategory, ABC):
+    '''@private'''
+    key: str
+    id:str|None =                    Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    @model_validator(mode='after')
+    def _validate_mandatory_fields(self):
+        if not self.id:
+            self._add_validation_message(
+                    source=f"Category {self.key}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f"Category key {self.key} is missing mandatory field 'ID'",
+                    highlight_pattern = f"{self.key}"
+            )
+        return self
+
+class Data_Result(Data_Abstract):
+    '''Represents the -DR category'''
+    key: str = Field(default='-DR', frozen=True)
+    id:str|None =                    Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    
+class Data_Method(Data_Abstract):
+    '''Represents the -DM category'''
+    key: str = Field(default='-DM', frozen=True)
+    id:str|None =                    Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    
+class Data_Calibration(Data_Abstract):
+    '''Represents the -DC category'''
+    key: str = Field(default='-DC', frozen=True)
+    id:str|None =                    Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    
+class Data_Progress(Data_Abstract):
+    '''Represents the -DP category'''
+    key: str = Field(default='-DP', frozen=True)
+    id:str|None =                    Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    
+class Data_Static(Data_Abstract):
+    '''Represents the -DS category'''
+    key: str = Field(default='-DS', frozen=True)
+    id:str|None =                    Field(              alias='21')
+    additional_segments: list[IDSegment] = Field(default_factory=list, exclude=True)
+    ''' Category segments, which are not defined in the specification'''
+    
+    

labfreed/PAC_ID/__init__.py

@@ -0,0 +1,19 @@
+from .pac_id import PAC_ID
+from .id_segment import IDSegment
+from .extension import Extension
+
+'''@private
+From a SW engineering perspective it would be best to have no dependencies from other modules to pac_id.
+However from a Python users convenience perspective it is better to have one place where a pac url can be parsed and magically the extensions are in a meaningful type (e.g. TREX in TREX aware format) and categories are known of possible.
+
+>> We have given priority to convenient usage and therefore chose to have dependencies from pac_id to pac_cat and well_known_extensions
+'''
+
+
+__all__ = [
+    "PAC_ID",
+    "IDSegment",
+    "Extension"
+]
+
+

labfreed/PAC_ID/extension.py

@@ -0,0 +1,48 @@
+
+from abc import ABC, abstractproperty
+
+from pydantic import model_validator
+
+from labfreed.labfreed_infrastructure import LabFREED_BaseModel
+
+    
+class ExtensionBase(ABC):
+    name: str
+    type: str
+
+
+    @abstractproperty
+    def data(self) -> str:
+        raise NotImplementedError("Subclasses must implement 'data'")
+    
+    
+
+
+class Extension(LabFREED_BaseModel,ExtensionBase):
+    '''Implementation of Extension for unknown extension types'''
+    name:str
+    type:str
+    data_:str
+    
+    @property
+    def data(self) -> str:
+        return self.data_
+       
+    @staticmethod
+    def create(*, name, type, data):
+        return Extension(name=name, type=type, data=data)
+    
+    @model_validator(mode='before')
+    @classmethod
+    def move_data_field(cls, values):
+        if "data" in values:
+            values["data_"] = values.pop("data")
+        return values
+    
+    model_config = {
+        "extra": "allow",  # Allow extra keys during pre-validation
+    }
+    
+    def __str__(self):
+        return f'{self.name}${self.type}/{self.data}'
+    

labfreed/PAC_ID/id_segment.py

@@ -0,0 +1,90 @@
+import re
+from pydantic import model_validator
+from labfreed.labfreed_infrastructure import LabFREED_BaseModel, ValidationMsgLevel, _quote_texts
+from labfreed.well_known_keys.labfreed.well_known_keys import WellKnownKeys
+
+
+_hsegment_pattern = r"[A-Za-z0-9_\-\.~!$&'()+,:;=@]|%[0-9A-Fa-f]{2}"
+
+class IDSegment(LabFREED_BaseModel):
+    """ Represents an id segment of a PAC-ID. It can be a value or a key value pair.
+    """
+    key:str|None = None
+    ''' The key of the segment. This is optional.'''
+    value:str
+    ''' The value of the segment. (mandatory)'''
+
+    @model_validator(mode="after")
+    def _validate_segment(self):
+        key = self.key or ""
+        value = self.value
+
+        # MUST be a valid hsegment according to RFC 1738, but without * (see PAC-ID Extension)
+        # This means it must be true for both, key and value
+        if not_allowed_chars := set(re.sub(_hsegment_pattern, '', key)):
+            self._add_validation_message(
+                    source=f"id segment key {key}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f"{_quote_texts(not_allowed_chars)} must not be used. The segment key must be a valid hsegment",
+                    highlight_pattern = key,
+                    highlight_sub = not_allowed_chars
+            )
+
+        if not_allowed_chars := set(re.sub(_hsegment_pattern, '', value)):
+            self._add_validation_message(
+                    source=f"id segment key {value}",
+                    level = ValidationMsgLevel.ERROR,
+                    msg=f"{_quote_texts(not_allowed_chars)} must not be used. The segment key must be a valid hsegment",
+                    highlight_pattern = value,
+                    highlight_sub = not_allowed_chars
+            )
+
+        # Segment key SHOULD be limited to A-Z, 0-9, and -+..
+        if not_recommended_chars := set(re.sub(r'[A-Z0-9-:+]', '', key)):
+            self._add_validation_message(
+                    source=f"id segment key {key}",
+                    level = ValidationMsgLevel.RECOMMENDATION,
+                    msg=f"{_quote_texts(not_recommended_chars)} should not be used. Characters SHOULD be limited to upper case letters (A-Z), numbers (0-9), '-' and '+' ",
+                    highlight_pattern = key,
+                    highlight_sub = not_recommended_chars
+                )
+
+        # Segment key should be in Well know keys
+        if key and key not in [k.value for k in WellKnownKeys]:
+            self._add_validation_message(
+                    source=f"id segment key {key}",
+                    level = ValidationMsgLevel.RECOMMENDATION,
+                    msg=f"{key} is not a well known segment key. It is RECOMMENDED to use well-known keys.",
+                    highlight_pattern = key,
+                    highlight_sub=[key]
+                )
+
+
+        # Segment value SHOULD be limited to A-Z, 0-9, and -+..
+        if not_recommended_chars := set(re.sub(r'[A-Z0-9-:+]', '', value)):
+            self._add_validation_message(
+                    source=f"id segment value {value}",
+                    level = ValidationMsgLevel.RECOMMENDATION,
+                    msg=f"Characters {_quote_texts(not_recommended_chars)} should not be used., Characters SHOULD be limited to upper case letters (A-Z), numbers (0-9), '-' and '+' ",
+                    highlight_pattern = value,
+                    highlight_sub = not_recommended_chars
+                )
+
+        # Segment value SHOULD be limited to A-Z, 0-9, and :-+ for new designs.
+        # this means that ":" in key or value is problematic
+        if ':' in key:
+            self._add_validation_message(
+                    source=f"id segment key {key}",
+                    level = ValidationMsgLevel.RECOMMENDATION,
+                    msg="Character ':' should not be used in segment key, since this character is used to separate key and value this can lead to undefined behaviour.",
+                    highlight_pattern = key
+                )
+        if ':' in value:
+            self._add_validation_message(
+                    source=f"id segment value {value}",
+                    level = ValidationMsgLevel.RECOMMENDATION,
+                    msg="Character ':' should not be used in segment value, since this character is used to separate key and value this can lead to undefined behaviour.",
+                    highlight_pattern = value
+                )
+
+        return self