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

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

labfreed/pac_id/pac_id.py

@@ -0,0 +1,140 @@
+import re
+from typing_extensions import Self
+from pydantic import Field, conlist, model_validator
+
+from labfreed.labfreed_infrastructure import LabFREED_BaseModel, ValidationMsgLevel
+from labfreed.pac_id.id_segment import IDSegment
+from labfreed.pac_id.extension import Extension
+
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    pass
+
+
+_domain_name_pattern = r"(?!-)([A-Za-z0-9-]{1,63}(?<!-)\.)+[A-Za-z]{2,63}"
+
+class PAC_ID(LabFREED_BaseModel):
+    '''Represents a PAC-ID. 
+    Refer to the [specification](https://github.com/ApiniLabs/PAC-ID?tab=readme-ov-file#specification) for details.
+    '''
+    issuer:str 
+    '''The issuer of the PAC-ID.'''
+    identifier: conlist(IDSegment) = Field(..., default_factory=list) # type: ignore # exclude=True prevents this from being serialized by Pydantic
+    '''The identifier of the PAC-ID is a series of IDSegments'''
+    
+    extensions: list[Extension] = Field(default_factory=list)
+    
+    
+    def get_extension_of_type(self, type:str) -> list[Extension]:
+        '''Get all extensions of a certain type.'''
+        return [e for e in self.extensions if e.type == type]
+    
+    
+    def get_extension(self, name:str) -> Extension|None:
+        '''Get extension of certain name'''
+        out = [e for e in self.extensions if e.name == name]
+        if not out:
+            return None
+        return out[0]
+    
+    @classmethod
+    def from_url(cls, url, *, extension_interpreters='default', 
+                 try_pac_cat=True,
+                 suppress_validation_errors=False) -> Self:
+        from labfreed.pac_id.url_parser import PAC_Parser
+        return PAC_Parser.from_url(url, try_pac_cat=try_pac_cat, suppress_validation_errors=suppress_validation_errors, extension_interpreters=extension_interpreters)
+    
+    def to_url(self, use_short_notation=False, uppercase_only=False) -> str:
+        from labfreed.pac_id.url_serializer import PACID_Serializer
+        return PACID_Serializer.to_url(self, use_short_notation=use_short_notation, uppercase_only=uppercase_only)
+    
+    def to_json(self, indent=None) -> str:
+        if not indent:
+            return self.model_dump_json()
+        else:
+            return self.model_dump_json(indent=indent)
+        
+    def to_dict(self) -> dict:
+        return self.model_dump()
+    
+    def __str__(self):
+        return self.to_url()
+          
+         
+    @model_validator(mode='after')
+    def _check_at_least_one_segment(self) -> Self:
+        if not len(self.identifier) >= 1:
+            self._add_validation_message(
+                        source="identifier",
+                        level = ValidationMsgLevel.ERROR,
+                        msg='Identifier must contain et least one segment.'
+                    )
+        return self
+    
+        
+    @model_validator(mode='after')
+    def _check_length(self) -> Self:
+        length = 0
+        for s in self.identifier:
+            s:IDSegment = s
+            if s.key:
+                length += len(s.key)
+                length += 1 # for ":"
+            length += len(s.value)
+        length += len(self.identifier) - 1 # account for "/" separating the segments
+        
+        if length > 256:
+            self._add_validation_message(
+                        source="identifier",
+                        level = ValidationMsgLevel.ERROR,
+                        msg=f'Identifier is {length} characters long, Identifier must not exceed 256 characters.'
+                    )
+        return self
+       
+    
+    @model_validator(mode="after")
+    def _validate_issuer(self):
+        if not re.fullmatch(_domain_name_pattern, self.issuer):
+            self._add_validation_message(
+                    source="PAC-ID",
+                    level = ValidationMsgLevel.ERROR,
+                    highlight_pattern=self.issuer,
+                    msg="Issuer must be a valid domain name. "
+                )
+         
+        # recommendation that A-Z, 0-9, -, and . should be used
+        if not_recommended_chars := set(re.sub(r'[A-Z0-9\.-]', '', self.issuer)):
+            self._add_validation_message(
+                    source="PAC-ID",
+                    level = ValidationMsgLevel.RECOMMENDATION,
+                    highlight_pattern=self.issuer,
+                    highlight_sub=not_recommended_chars,
+                    msg=f"Characters {' '.join(not_recommended_chars)} should not be used. Issuer SHOULD contain only the characters A-Z, 0-9, -, and . "
+                )
+        return self
+    
+    
+    @model_validator(mode='after')
+    def _check_identifier_segment_keys_are_unique(self) -> Self:
+        keys = [s.key for s in self.identifier 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.RECOMMENDATION,
+                    msg=f"Duplicate segment key {k}. This will probably lead to undefined behaviour",
+                    highlight_pattern = k
+                )
+        return self
+    
+    
+
+    
+    
+
+    
+    
+
+

labfreed/pac_id/url_parser.py

@@ -0,0 +1,154 @@
+
+
+import re
+from types import MappingProxyType
+
+from labfreed.labfreed_infrastructure import LabFREED_ValidationError
+
+from labfreed.pac_id.id_segment import IDSegment
+from labfreed.pac_id.extension import Extension
+
+from labfreed.pac_cat import PAC_CAT
+from labfreed.well_known_extensions import default_extension_interpreters
+
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    # only imported during type checking
+    from labfreed.pac_id import PAC_ID
+    from labfreed.pac_cat import PAC_CAT
+
+class PAC_Parser():
+    '''@private
+    Knows how to parse a PAC-ID. 
+    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
+   '''
+      
+    @classmethod
+    def from_url(cls, pac_url:str, 
+                 *, 
+                 extension_interpreters = 'default', 
+                 try_pac_cat = True,
+                 suppress_validation_errors=False
+                 ) -> "PAC_ID":
+        """Parses a PAC-ID with extensions
+
+        Args:
+            pac_url (str): pac id with optional extensions: e.g. HTTPS://PAC.METTORIUS.COM/-MD/BAL500/1234*N$N/ABC*SUM$TREX/A$T.A:ABC
+
+        Raises:
+            LabFREED_ValidationError: When validation fails. Note,that with suppress_errors no such error is raises
+
+        Returns:
+            PACID including extensions. If possible PAC-CAT is applied and extensions are cast to a known type, which knows how to inetrprete the data
+        """
+        if extension_interpreters == 'default':
+            extension_interpreters = default_extension_interpreters
+        
+        if '*' in pac_url:
+            id_str, ext_str = pac_url.split('*', 1)
+        else:
+            id_str = pac_url
+            ext_str = ""
+                    
+        pac_id = cls._parse_pac_id(id_str)
+        
+        # try converting to PAC-CAT. This can fail, in which case a regular PAC-ID is returned
+        if try_pac_cat:
+            try:
+                pac_cat = PAC_CAT.from_pac_id(pac_id)
+                if pac_cat.categories:
+                    pac_id = pac_cat
+            except LabFREED_ValidationError:
+                pass 
+              
+        extensions = cls._parse_extensions(ext_str)
+        if extensions and extension_interpreters:
+            for i, e in enumerate(extensions):
+                if interpreter := extension_interpreters.get(e.type):
+                    extensions[i] = interpreter.from_extension(e)
+        pac_id.extensions = extensions
+            
+        if not pac_id.is_valid and not suppress_validation_errors:
+            raise LabFREED_ValidationError(validation_msgs = pac_id._get_nested_validation_messages())
+        
+        return pac_id
+            
+    @classmethod
+    def _parse_pac_id(cls,id_str:str) -> "PAC_ID":
+        # m = re.match('(HTTPS://)?(PAC.)?(?P<issuer>.+?\..+?)/(?P<identifier>.*)', id_str)
+        m = re.match('(HTTPS://)?(PAC.)?(?P<issuer>.+?)/(?P<identifier>.*)', id_str)
+        d = m.groupdict()
+        
+        id_segments = list()
+        id_segments = cls._parse_id_segments(d.get('identifier'))
+        
+        from labfreed.pac_id import PAC_ID
+        pac = PAC_ID(issuer= d.get('issuer'),
+                     identifier=id_segments
+        )
+        
+        return pac
+    
+    @classmethod
+    def _parse_id_segments(cls, identifier:str):
+        if not identifier:
+            return []    
+        
+        id_segments = list()  
+        if len(identifier) > 0 and identifier[0] == '/':
+            identifier = identifier[1:]
+        for s in identifier.split('/'):
+            tmp = s.split(':')
+            
+            if len(tmp) == 1:
+                segment = IDSegment(value=tmp[0])
+            elif len(tmp) == 2:
+                segment = IDSegment(key=tmp[0], value=tmp[1])
+            else:
+                raise ValueError(f'invalid segment: {s}')
+                
+            id_segments.append(segment)
+        return id_segments
+    
+
+    @classmethod
+    def _parse_extensions(cls, extensions_str:str|None) -> list["Extension"]:    
+        
+        extensions = list()
+        
+        if not extensions_str:
+            return extensions
+        
+        defaults =  MappingProxyType(
+                                {
+                                    0: { 'name': 'N', 'type': 'N'},
+                                    1: { 'name': 'SUM', 'type': 'TREX'}
+                                }
+        )
+        for i, e in enumerate(extensions_str.split('*')):
+            if e == '': #this will happen if first extension starts with *
+                continue
+            d = re.match('((?P<name>.+)\$(?P<type>.+)/)?(?P<data>.+)', e).groupdict()
+            
+            name = d.get('name')
+            type = d.get('type') 
+            data = d.get('data')
+    
+            if name:
+                defaults = None # once a name was specified no longer assign defaults
+            else:
+                if defaults:
+                    name = defaults.get(i).get('name')
+                    type = defaults.get(i).get('type')
+                else:
+                    raise ValueError('extension number {i}, must have name and type')
+            
+            #convert to subtype if they were given
+            e = Extension.create(name=name, type=type, data=data)
+            extensions.append(e)
+
+        return extensions