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

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

labfreed/PAC_ID/url_serializer.py

@@ -0,0 +1,80 @@
+from labfreed.pac_cat.pac_cat import PAC_CAT
+from labfreed.pac_cat.predefined_categories import PredefinedCategory
+from labfreed.pac_id.id_segment import IDSegment
+from labfreed.pac_id.extension import Extension
+from labfreed.pac_id import PAC_ID  
+
+
+class PACID_Serializer():
+    '''Represents a PAC-ID including it's extensions'''
+  
+    @classmethod
+    def to_url(cls, pac:PAC_ID, use_short_notation=False, uppercase_only=False) -> str:
+        """Serializes the PAC-ID including extensions.
+
+        Args:
+            use_short_notation (bool, optional): Uses shortening conventions for extensions and categories..
+            uppercase_only (bool, optional): Forces all uppercase letters (results in smaller QR)..
+
+        Returns:
+            str: Something like this HTTPS://PAC.METTORIUS.COM/-MD/BAL500/1234*N$N/ABC*SUM$TREX/A$T.A:ABC
+
+        """
+        extensions_str = cls._serialize_extensions(pac.extensions, use_short_notation=use_short_notation)
+            
+        identifier_str = cls._serialize_identifier(pac, use_short_notation=use_short_notation)
+        out = f"HTTPS://PAC.{pac.issuer}{identifier_str}{extensions_str}"
+        
+        if uppercase_only:
+            out = out.upper()
+        return out
+    
+    @classmethod
+    def _serialize_identifier(cls, pac:PAC_ID|PAC_CAT, use_short_notation=True):
+        ''' Serializes the PAC-ID'''
+        if isinstance(pac, PAC_CAT):
+            for c in pac.categories:
+                segments = [IDSegment(value=c.key)]
+                if isinstance(c, PredefinedCategory):
+                    segments += c._get_segments(use_short_notation=use_short_notation)
+                else:
+                    segments += c.segments
+        else:
+            segments = pac.identifier
+        
+        identifier_str = ''
+        for s in segments:
+            s:IDSegment = s
+            if s.key:
+                identifier_str += f'/{s.key}:{s.value}'
+            else:
+                identifier_str += f'/{s.value}'
+        return identifier_str
+          
+
+    @classmethod
+    def _serialize_extensions(cls, extensions:list[Extension], use_short_notation):
+        out = ''
+        short_notation = use_short_notation
+        for i, e in enumerate(extensions):
+            
+            if short_notation and i==0:
+                if e.name=='N':
+                    out += f'*{e.data}'
+                    continue
+                else: 
+                    short_notation = False
+            if short_notation and i==1:
+                if e.name=='SUM':
+                    out += f'*{e.data}'
+                    continue
+                else: 
+                    short_notation = False
+                
+            out += f'*{e.name}${e.type}/{e.data}'
+        return out
+        
+
+
+
+

labfreed/PAC_ID_Resolver/__init__.py

@@ -0,0 +1,2 @@
+from .resolver import PAC_ID_Resolver, load_cit  # noqa: F401
+from .services import ServiceGroup  # noqa: F401

labfreed/PAC_ID_Resolver/cit_v1.py

@@ -0,0 +1,149 @@
+
+from enum import Enum
+import logging
+import re
+
+from pydantic import Field
+from labfreed.labfreed_infrastructure import LabFREED_BaseModel, ValidationMessage, ValidationMsgLevel
+from labfreed.pac_id.pac_id import PAC_ID
+from labfreed.pac_id_resolver.services import Service, ServiceGroup
+
+class ServiceType(Enum):
+    USER_HANDOVER_GENERIC = 'userhandover-generic'
+    ATTRIBUTE_SERVICE_GENERIC = 'attributes-generic'
+
+
+class CITEntry_v1(LabFREED_BaseModel):
+    applicable_if: str = Field(..., min_length=1)
+    service_name: str = Field(..., min_length=1)
+    application_intent:str = Field(..., min_length=1)
+    service_type:ServiceType
+    template_url:str = Field(..., min_length=1)
+
+
+class CIT_v1(LabFREED_BaseModel):
+    origin:str = ''
+    entries:list[CITEntry_v1]
+    
+    
+    @classmethod
+    def from_csv(cls, csv:str, origin=''):
+        lines = csv.splitlines()
+        entries = list()
+        errors = list()
+        for line in lines:
+            if not line: # empty line
+                continue
+            if line.strip()[0] == '#': #comment line
+                continue
+            if 'Service Name' in line.strip() : #header line
+                continue
+            
+            cols = [c.strip() for c in line.split('\t')]
+            try:
+                entry = CITEntry_v1(
+                                    service_name         = cols[0],
+                                    application_intent   = cols[1],
+                                    service_type         = ServiceType(cols[2]),
+                                    applicable_if        = cols[3],
+                                    template_url         = cols[4]
+                                    )
+            except ValueError:
+                logging.error(f'invalid line {line}')
+                msg = ValidationMessage(
+                    level=ValidationMsgLevel.WARNING,
+                    source='CIT line',
+                    source_id=0,
+                    msg='Invalid line in CIT. Line was ignored. Remaining CIT is functional.',
+                    highlight_sub_patterns=line
+                )
+                errors.append(msg)
+
+            entries.append(entry)           
+        cit = CIT_v1(origin=origin, entries=entries)
+        cit._validation_messages.extend(errors)
+        cit._csv_original = csv
+        return cit
+    
+    def evaluate_pac_id(self, pac):
+        cit_evaluated = ServiceGroup(origin=self.origin)   
+        for e in self.entries:
+            conditions = e.applicable_if.split(';')
+            conditions_evaluated = list()
+            for c in conditions:
+                if '=' in c:
+                    query, expected = c.split('=')
+                    value = self._find_in_pac(query.strip(), pac)
+                    conditions_evaluated.append(value == expected.strip())
+                else:
+                    query = c.strip()
+                    found = self._find_in_pac(query, pac)
+                    conditions_evaluated.append(found)
+            is_applicable = all(conditions_evaluated)
+                    
+            if not is_applicable:
+                continue
+
+            url = re.sub(r"\{([^}]+)\}", lambda v: self._find_in_pac(v.group(0), pac), e.template_url)
+            cit_evaluated.services.append(Service(  
+                                                    service_name=e.service_name,
+                                                    application_intents= [ e.application_intent ],
+                                                    service_type=e.service_type,
+                                                    url = url
+                                )
+                            )            
+        return cit_evaluated
+    
+    def _find_in_pac(self, value, pac:PAC_ID):
+        pac_url =pac.to_url()
+        if value == '{isu}':
+            return pac.issuer
+        
+        elif value == '{pac}':
+            return pac_url.split('*')[0]
+        
+        elif value == '{id}':
+            m = re.match(r'^HTTPS://.+?/(.+?)(\*.*)*$', pac_url)
+            return m.group(1) if m else None
+        
+        elif m := re.match(r'\{idSeg(\d+)\}', value):
+            i = int(m.group(1)) - 1 # CIT is 1 based
+            seg = pac.identifier[i] if i < len(pac.identifier) else None
+            if seg:
+                return f"{(seg.key + ':') if seg.key else ""}{seg.value}"
+            
+        elif m := re.match(r'\{idVal(\w+)\}', value):
+            k = m.group(1)
+            seg = [s for s in pac.identifier if s.key and s.key == k]
+            if seg:
+                seg = seg[0]
+                return seg.value   
+            else:
+                return None 
+            
+        elif value == '{ext}':
+            m = re.match(r'^.*?(\*.*)*$', pac_url)
+            ext_str = m.group(1) if m else None
+            return m.group(1)[1:] if ext_str else None
+        
+        elif m := re.match(r'\{ext(\d+)\}', value):
+            i = int(m.group(1)) - 1 # CIT is 1 based
+            extensions = pac_url.split('*') 
+            extensions.pop(0)# first element is not extension
+            return extensions[i] if i < len(extensions) else None
+        else:
+            return None
+                
+
+            
+        
+    
+    def __str__(self):
+        if csv:=self._csv_original:
+            return csv
+        
+        s = "# coupling information table version: 1.0\n"
+        s += "Service Name\tApplication Intent\tService Type\tApplicable If\tTemplate Url\n"
+        for e in self.entries:
+            s += '\t'.join([e.service_name, e.application_intent, e.service_type.value, e.applicable_if, e.template_url]) + '\n'
+        return s