labfreed 0.1.0__tar.gz → 0.2.0__tar.gz

labfreed-0.2.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,78 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+
+      - name: Run Ruff linter
+        run: |
+          ruff check . || true
+
+      - name: Run tests
+        run: |
+          pytest tests 
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      url: https://pypi.org/project/labfreed/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

labfreed-0.2.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+## Change Log
+### v0.2.0b2
+- improvements in api consistency and ease of use
+- restructured code for better separation of concerns
+- support for coupling information table v1
+
+### v0.1.1
+- minor internal improvements and bugfixes
+  
+### v0.1.0
+- DRAFT Support for PAC-ID Resolver
+
+### v0.0.20
+- bugfix in TREX table to dict conversion
+- markdown compatible validation printing 
+
+### v0.0.19
+- supports PAC-ID, PAC-CAT, TREX and DisplayName
+- QR generation 
+- ok-ish test coverage
+
+# Attributions
+The following tools were used:
+- [pdoc](https://pdoc.dev/) was a great help with generating documentation
+- [Pydantic](https://docs.pydantic.dev/latest/)
+- json with UNECE units from (https://github.com/quadient/unece-units/blob/main/python/src/unece_excel_parser/parsedUneceUnits.json)
+- json with GS1 codes from (https://ref.gs1.org/ai/GS1_Application_Identifiers.jsonld)
+
+

labfreed-0.2.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: labfreed
+Version: 0.2.0
+Summary: Python implementation of LabFREED building blocks
+Author-email: Reto Thürer <thuerer.r@buchi.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+License-File: LICENSE
+Requires-Dist: numpy>=2.2.4
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: segno>=1.6.6
+Requires-Dist: typer>=0.15.2
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: jsonpath-ng>=1.7.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: pytest>=8.3.5 ; extra == "dev"
+Requires-Dist: pdoc>=15.0.1 ; extra == "dev"
+Requires-Dist: flit>=3.12.0 ; extra == "dev"
+Requires-Dist: ruff>=0.11.5 ; extra == "dev"
+Provides-Extra: dev
+
+# LabFREED for Python
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/labfreed.svg)](https://pypi.org/project/labfreed/) ![Python Version](https://img.shields.io/pypi/pyversions/labfreed)
+
+<!--
+[![Tests](https://github.com/retothuerer/LabFREED/actions/workflows/ci.yml/badge.svg)](https://github.com/retothuerer/LabFREED/actions/workflows/ci.yml)
+-->
+
+This is a Python implementation of [LabFREED](https://labfreed.wega-it.com) building blocks.
+
+## Supported Building Blocks
+- PAC-ID
+  - Parsing
+  - Serialization
+- PAC-CAT
+  - Interpretation of PAC-ID as categories
+- T-REX
+  - Parsing 
+  - Serialization
+- Display Extension
+  - base36 <> str conversions
+- PAC-ID Resolver
+  - support for CIT v1
+  - draft support for CIT v1 (improved version)
+  - combined use of multiple cit in any combination of version
+- Generation of QR codes (PAC-ID with extensions)
+  
+- Validation (with Errors Recommendations)
+
+## Installation
+You can install LabFREED from [PyPI](https://pypi.org/project/labfreed/) using pip:
+
+```bash
+pip install labfreed
+```
+
+
+## Usage Examples
+> ⚠️ **Note:** These examples are building on each other. Imports and parsing are not repeated in each example.
+<!-- BEGIN EXAMPLES -->
+```python
+# import built ins
+import os
+
+target = 'console'
+```
+### Parse a simple PAC-ID
+
+```python
+# Parse the PAC-ID
+from labfreed.labfreed_infrastructure import LabFREED_ValidationError  # noqa: E402
+from labfreed import PAC_ID, LabFREED_ValidationError  # noqa: E402, F811
+
+pac_str = 'HTTPS://PAC.METTORIUS.COM/-MD/bal500/@1234'
+try:
+    pac = PAC_ID.from_url(pac_str)
+except LabFREED_ValidationError:
+    pass
+# Check validity of this PAC-ID
+is_valid = pac.is_valid
+print(f'PAC-ID is valid: {is_valid}')
+```
+```text
+>> PAC-ID is valid: True
+```
+### Show recommendations:
+Note that the PAC-ID -- while valid -- uses characters which are not recommended (results in larger QR code).
+There is a nice function to highlight problems
+
+```python
+pac.print_validation_messages(target=target)
+```
+```text
+>> Validation Results                                                                                                                   
+>> ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+>> │ RECOMMENDATION  in id segment value bal500                                                                                        │
+>> │ Characters 'l','a','b' should not be used., Characters SHOULD be limited to upper case letters (A-Z), numbers (0-9), '-' and '+'  │
+>> │                                                                                                                                   │
+>> │ HTTPS://PAC.METTORIUS.COM/-MD/240:bal500/21:@1234                                                                                 │
+>> ├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+>> │ RECOMMENDATION  in id segment value @1234                                                                                         │
+>> │ Characters '@' should not be used., Characters SHOULD be limited to upper case letters (A-Z), numbers (0-9), '-' and '+'          │
+>> │                                                                                                                                   │
+>> │ HTTPS://PAC.METTORIUS.COM/-MD/240:bal500/21:@1234                                                                                 │
+>> ├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+>> │ RECOMMENDATION  in id segment value bal500                                                                                        │
+>> │ Characters 'l','a','b' should not be used., Characters SHOULD be limited to upper case letters (A-Z), numbers (0-9), '-' and '+'  │
+>> │                                                                                                                                   │
+>> │ HTTPS://PAC.METTORIUS.COM/-MD/240:bal500/21:@1234                                                                                 │
+>> ├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+>> │ RECOMMENDATION  in id segment value @1234                                                                                         │
+>> │ Characters '@' should not be used., Characters SHOULD be limited to upper case letters (A-Z), numbers (0-9), '-' and '+'          │
+>> │                                                                                                                                   │
+>> │ HTTPS://PAC.METTORIUS.COM/-MD/240:bal500/21:@1234                                                                                 │
+>> └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+### Save as QR Code
+
+```python
+from labfreed.qr import save_qr_with_markers  # noqa: E402
+
+save_qr_with_markers(pac_str, fmt='png')
+```
+```text
+>> Large QR: Provided URL is not alphanumeric!
+>> Size: 29
+>> Version: 3
+>> Error Level: M
+```
+### PAC-CAT
+PAC-CAT defines a (optional) way how the identifier is structured.
+PAC_ID.from_url() automatically converts to PAC-CAT if possible.
+
+```python
+from labfreed.pac_cat import PAC_CAT  # noqa: E402
+pac_str = 'HTTPS://PAC.METTORIUS.COM/-DR/XQ908756/-MD/bal500/@1234'
+pac = PAC_ID.from_url(pac_str)
+if isinstance(pac, PAC_CAT):
+    categories = pac.categories 
+    pac.print_categories()
+```
+```text
+>> Categories in           
+>> HTTPS://PAC.METTORIUS.COM/-MD/240:
+>>          bal500/21:@1234          
+>> ┌────────────────────┬───────────┐
+>> │ Main Category      │           │
+>> │ key ()             │  -DR      │
+>> │ id (21)            │  XQ908756 │
+>> ├────────────────────┼───────────┤
+>> │ Category           │           │
+>> │ key ()             │  -MD      │
+>> │ model_number (240) │  bal500   │
+>> │ serial_number (21) │  @1234    │
+>> └────────────────────┴───────────┘
+```
+### Parse a PAC-ID with extensions
+PAC-ID can have extensions. Here we parse a PAC-ID with attached display names and summary.
+
+```python
+pac_str = 'HTTPS://PAC.METTORIUS.COM/-MD/BAL500/1234*N$N/WM633OV3E5DGJW2BEG0PDM1EA7*SUM$TREX/WEIGHT$GRM:67.89'
+pac = PAC_ID.from_url(pac_str)
+```
+#### Display Name
+Note that the Extension is automatically converted to a DisplayNameExtension
+
+```python
+display_name = pac.get_extension('N') # display name has name 'N'
+print(display_name) 
+```
+```text
+>> Display name: My Balance ❤️
+```
+#### TREX
+
+```python
+trexes = pac.get_extension_of_type('TREX')
+trex_extension = trexes[0] # there could be multiple trexes. In this example there is only one, though
+trex = trex_extension.trex
+v = trex.get_segment('WEIGHT')
+print(f'WEIGHT = {v.value}')
+```
+```text
+>> WEIGHT = 67.89
+```
+### Create a PAC-ID with Extensions
+
+#### Create PAC-ID
+
+```python
+from labfreed.pac_id import PAC_ID, IDSegment  # noqa: E402
+from labfreed.well_known_keys.labfreed.well_known_keys import WellKnownKeys  # noqa: E402
+
+pac = PAC_ID(issuer='METTORIUS.COM', identifier=[IDSegment(key=WellKnownKeys.SERIAL, value='1234')])
+pac_str = pac.to_url()
+print(pac_str)
+```
+```text
+>> HTTPS://PAC.METTORIUS.COM/21:1234
+```
+#### Create a TREX 
+TREX can conveniently be created from a python dictionary.
+Note that utility types for Quantity (number with unit) and table are needed
+
+```python
+from datetime import datetime  # noqa: E402
+from labfreed.trex.python_convenience.pyTREX import pyTREX  # noqa: E402
+from labfreed.trex.python_convenience.data_table import DataTable  # noqa: E402
+from labfreed.trex.python_convenience.quantity import Quantity  # noqa: E402
+
+# Value segments of different type
+segments = {
+                'STOP': datetime(year=2024,month=5,day=5,hour=13,minute=6),
+                'TEMP': Quantity(value=10.15, unit= 'K'),
+                'OK':False,
+                'COMMENT': 'FOO',
+                'COMMENT2':'£'
+            }
+mydata = pyTREX(segments) 
+
+# Create a table
+table = DataTable(col_names=['DURATION', 'Date', 'OK', 'COMMENT'])
+table.append([Quantity(value=1, unit= 'hour'), datetime.now(), True, 'FOO'])
+table.append([                                                 1.1,  datetime.now(), True, 'BAR'])
+table.append([                                                 1.3,  datetime.now(), False, 'BLUBB'])
+#add the table to the pytrex
+mydata.update({'TABLE': table})
+
+# Create TREX
+trex = mydata.to_trex()
+
+
+# Validation also works the same way for TREX
+trex.print_validation_messages(target=target)
+```
+```text
+>> Validation Results                                            
+>> ┌────────────────────────────────────────────────────────────┐
+>> │ ERROR  in TREX table column Date                           │
+>> │ Column header key contains invalid characters: 'e','t','a' │
+>> │                                                            │
+>> │ STOP$T.D:20240505T1306                                     │
+>> │ +TEMP$KEL:10.15                                            │
+>> │ +OK$T.B:F                                                  │
+>> │ +COMMENT$T.A:FOO                                           │
+>> │ +COMMENT2$T.T:QMDTNXIKU                                    │
+>> │ +TABLE$$DURATION$HUR:Date$T.D:OK$T.B:COMMENT$T.A::         │
+>> │  1:20250423T170126.335:T:FOO::                             │
+>> │  1.1:20250423T170126.335:T:BAR::                           │
+>> │  1.3:20250423T170126.335:F:BLUBB                           │
+>> └────────────────────────────────────────────────────────────┘
+```
+#### Combine PAC-ID and TREX and serialize
+
+```python
+from labfreed.well_known_extensions import TREX_Extension  # noqa: E402
+pac.extensions = [TREX_Extension(name='MYTREX', trex=trex)]
+pac_str = pac.to_url()
+print(pac_str)
+```
+```text
+>> HTTPS://PAC.METTORIUS.COM/21:1234*MYTREX$TREX/STOP$T.D:20240505T1306+TEMP$KEL:10.15+OK$T.B:F+COMMENT$T.A:FOO+COMMENT2$T.T:QMDTNXIKU+TABLE$$DURATION$HUR:Date$T.D:OK$T.B:COMMENT$T.A::1:20250423T170126.335:T:FOO::1.1:20250423T170126.335:T:BAR::1.3:20250423T170126.335:F:BLUBB
+```
+## PAC-ID Resolver
+
+```python
+from labfreed.pac_id_resolver import PAC_ID_Resolver, load_cit  # noqa: E402
+# Get a CIT
+dir = os.path.join(os.getcwd(), 'examples')
+p = os.path.join(dir, 'cit_mine.yaml')       
+cit = load_cit(p)
+
+# validate the CIT
+cit.is_valid
+cit.print_validation_messages(target=target)
+```
+```python
+# get a second cit
+p = os.path.join(dir, 'coupling-information-table')       
+cit2 = load_cit(p)
+cit2.origin = 'MY_COMPANY'
+```
+```python
+# resolve a pac id
+pac_str = 'HTTPS://PAC.METTORIUS.COM/-MS/X3511/CAS:7732-18-5'
+service_groups = PAC_ID_Resolver(cits=[cit, cit2]).resolve(pac_str)
+for sg in service_groups:
+    sg.update_states()
+    sg.print()
+    
+```
+```text
+>> Services from origin 'PERSONAL                         
+>> ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
+>> ┃ Service Name ┃ URL                                               ┃ Reachable ┃
+>> ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
+>> │ CAS Search   │ https://pubchem.ncbi.nlm.nih.gov/#query=7732-18-5 │ ACTIVE    │
+>> └──────────────┴───────────────────────────────────────────────────┴───────────┘
+>>                                     Services from origin 'MY_COMPANY                                    
+>> ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
+>> ┃ Service Name        ┃ URL                                                                ┃ Reachable ┃
+>> ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
+>> │ Chemical Management │ https://chem-manager.com/METTORIUS.COM/-MS/240:X3511/CAS:7732-18-5 │ INACTIVE  │
+>> └─────────────────────┴────────────────────────────────────────────────────────────────────┴───────────┘
+>>              Services from origin 'METTORIUS.COM              
+>> ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
+>> ┃ Service Name ┃ URL                             ┃ Reachable ┃
+>> ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
+>> │ CoA          │ https://mettorius.com/CoA.pdf   │ ACTIVE    │
+>> │ MSDS         │ https://mettorius.com/MSDS.pdf  │ ACTIVE    │
+>> │ Shop         │ https://mettorius.com/shop.html │ ACTIVE    │
+>> └──────────────┴─────────────────────────────────┴───────────┘
+```
+<!-- END EXAMPLES -->
+
+
+
+<!-- BEGIN CHANGELOG -->
+## Change Log
+### v0.2.0b2
+- improvements in api consistency and ease of use
+- restructured code for better separation of concerns
+- support for coupling information table v1
+
+### v0.1.1
+- minor internal improvements and bugfixes
+  
+### v0.1.0
+- DRAFT Support for PAC-ID Resolver
+
+### v0.0.20
+- bugfix in TREX table to dict conversion
+- markdown compatible validation printing 
+
+### v0.0.19
+- supports PAC-ID, PAC-CAT, TREX and DisplayName
+- QR generation 
+- ok-ish test coverage
+
+# Attributions
+The following tools were used:
+- [pdoc](https://pdoc.dev/) was a great help with generating documentation
+- [Pydantic](https://docs.pydantic.dev/latest/)
+- json with UNECE units from (https://github.com/quadient/unece-units/blob/main/python/src/unece_excel_parser/parsedUneceUnits.json)
+- json with GS1 codes from (https://ref.gs1.org/ai/GS1_Application_Identifiers.jsonld)
+<!-- END CHANGELOG -->