mgtx-benchling-wrapper 0.1.0__tar.gz

mgtx_benchling_wrapper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ana Valinhas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mgtx_benchling_wrapper-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: mgtx-benchling-wrapper
+Version: 0.1.0
+Summary: Python wrapper for Benchling API with common functions used at MGTX DSC
+Author-email: Ana Valinhas <ana.valinhas@meiragtx.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: benchling-sdk>=1.21.2
+Requires-Dist: benchling-api-client>=2.0.342
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: numpy>=1.26.4
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# mgtx-benchling-wrapper
+A wrapper of the Benchling API with common functions and workflows used at MGTX DSC.
+
+## Installation 🚀
+You can install this package using:
+```
+pip install mgtx-benchling-wrapper
+```
+
+## Quickstart 🚩
+After creating an app on your Benchling tenant, create a config.yaml file in your repo.
+The following are the contents of the config.yaml
+```
+BenchlingCredentials:
+  benchling_url: 'https://mytenant.benchling.com'
+  benchling_access_token: 'https://mytenant.benchling.com/api/v2/token'
+  app_client_id: 'your-app-client-id'
+  app_client_secret: 'encrypted-client-secret'
+AssaySchema:
+  schema_id: "schema_api_id"
+Project:
+  project_id: "project_api_id"
+```
+The app_client_secret should be encrypted. Create encryption.py Use cryptography as follows:
+```
+from cryptography.fernet import Fernet
+
+def decrypt(value):
+    return f.decrypt(value.encode()).decode()
+
+def encrypt(value):
+    return f.encrypt(value.encode()).decode()
+    
+if __name__ == "__main__":
+# Run this to print an encrypted string of "my-value"
+print(encrypt('your-app-client-secret))
+```
+The following is an example of the use of the assay_results_ingestion workflow.
+```
+import yaml
+from encryption import decrypt
+from mgtx_benchling_wrapper.context.benchling_context import BenchlingContext
+from mgtx_benchling_wrapper.wrapper.facade import BenchlingWrapperFacade
+from mgtx_benchling_wrapper.workflows.assays_result_ingestion import (
+     AssayResultIngestionWorkflow
+)
+
+def config():
+    with open("tests/config/test_config.yml") as f:
+        return yaml.safe_load(f)
+
+#create the benchling context        
+ctx = BenchlingContext(
+        base_url=config()['BenchlingCredentials']['benchling_url'],
+        client_id=config()['BenchlingCredentials']['app_client_id'],
+        client_secret=decrypt(config()['BenchlingCredentials']['app_client_secret']),
+        token_url=config()['BenchlingCredentials']['benchling_access_token'],
+    )    
+
+#initialize the wrapper
+wrapper = BenchlingWrapperFacade(ctx.benchling())
+
+#retrieve assay_schema_id
+schema_id = config()['AssaySchema']['schema_id']
+
+#retrieve project_id
+project_id = config()['Project']['project_id']
+
+#initiate results ingestion workflow
+results_ingestion = AssayResultIngestionWorkflow(wrapper)
+
+#ingest results on benchling
+list_missing_entities = results_ingestion.assay_results_ingestion_updated(
+        [dataframe_to_ingest],
+        schema_id,
+        project_id,
+        unique_identifiers =['assay_run_id', 'sample_id']
+        )       
+```
+
+

mgtx_benchling_wrapper-0.1.0/README.md

@@ -0,0 +1,81 @@
+# mgtx-benchling-wrapper
+A wrapper of the Benchling API with common functions and workflows used at MGTX DSC.
+
+## Installation 🚀
+You can install this package using:
+```
+pip install mgtx-benchling-wrapper
+```
+
+## Quickstart 🚩
+After creating an app on your Benchling tenant, create a config.yaml file in your repo.
+The following are the contents of the config.yaml
+```
+BenchlingCredentials:
+  benchling_url: 'https://mytenant.benchling.com'
+  benchling_access_token: 'https://mytenant.benchling.com/api/v2/token'
+  app_client_id: 'your-app-client-id'
+  app_client_secret: 'encrypted-client-secret'
+AssaySchema:
+  schema_id: "schema_api_id"
+Project:
+  project_id: "project_api_id"
+```
+The app_client_secret should be encrypted. Create encryption.py Use cryptography as follows:
+```
+from cryptography.fernet import Fernet
+
+def decrypt(value):
+    return f.decrypt(value.encode()).decode()
+
+def encrypt(value):
+    return f.encrypt(value.encode()).decode()
+    
+if __name__ == "__main__":
+# Run this to print an encrypted string of "my-value"
+print(encrypt('your-app-client-secret))
+```
+The following is an example of the use of the assay_results_ingestion workflow.
+```
+import yaml
+from encryption import decrypt
+from mgtx_benchling_wrapper.context.benchling_context import BenchlingContext
+from mgtx_benchling_wrapper.wrapper.facade import BenchlingWrapperFacade
+from mgtx_benchling_wrapper.workflows.assays_result_ingestion import (
+     AssayResultIngestionWorkflow
+)
+
+def config():
+    with open("tests/config/test_config.yml") as f:
+        return yaml.safe_load(f)
+
+#create the benchling context        
+ctx = BenchlingContext(
+        base_url=config()['BenchlingCredentials']['benchling_url'],
+        client_id=config()['BenchlingCredentials']['app_client_id'],
+        client_secret=decrypt(config()['BenchlingCredentials']['app_client_secret']),
+        token_url=config()['BenchlingCredentials']['benchling_access_token'],
+    )    
+
+#initialize the wrapper
+wrapper = BenchlingWrapperFacade(ctx.benchling())
+
+#retrieve assay_schema_id
+schema_id = config()['AssaySchema']['schema_id']
+
+#retrieve project_id
+project_id = config()['Project']['project_id']
+
+#initiate results ingestion workflow
+results_ingestion = AssayResultIngestionWorkflow(wrapper)
+
+#ingest results on benchling
+list_missing_entities = results_ingestion.assay_results_ingestion_updated(
+        [dataframe_to_ingest],
+        schema_id,
+        project_id,
+        unique_identifiers =['assay_run_id', 'sample_id']
+        )       
+```
+
+

mgtx_benchling_wrapper-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mgtx-benchling-wrapper"
+version = "0.1.0"
+description = "Python wrapper for Benchling API with common functions used at MGTX DSC"
+readme = "README.md"
+authors = [
+    { name = "Ana Valinhas", email = "ana.valinhas@meiragtx.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+
+dependencies = [
+    "benchling-sdk>=1.21.2",
+    "benchling-api-client>=2.0.342",
+    "pandas>=2.2.2",
+    "numpy>=1.26.4"
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-mock>=3.15.1",
+    "build",
+    "twine"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

mgtx_benchling_wrapper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/client/benchling_client.py

@@ -0,0 +1,67 @@
+from typing import Callable
+
+from benchling_sdk.benchling import Benchling
+from benchling_api_client.benchling_client import BenchlingApiClient
+from benchling_sdk.helpers.retry_helpers import RetryStrategy
+
+
+# -----------------------------
+# Configuration defaults
+# -----------------------------
+
+DEFAULT_TIMEOUT_SECONDS = 180
+MAX_RETRIES = 10
+BACKOFF_FACTOR = 2.0
+
+# -----------------------------
+# Client decorators
+# -----------------------------
+
+def with_default_timeout(client: BenchlingApiClient) -> BenchlingApiClient:
+    """
+    Apply default timeout to all Benchling API calls.
+    """
+    return client.with_timeout(DEFAULT_TIMEOUT_SECONDS)
+
+
+# -----------------------------
+# Factory
+# -----------------------------
+
+def with_backoff_timeout():
+    return RetryStrategy(
+        max_tries=MAX_RETRIES,
+        backoff_factor=BACKOFF_FACTOR
+    )
+
+def create_benchling_client(
+    *,
+    url: str,
+    auth,
+    client_decorator: Callable[[BenchlingApiClient], BenchlingApiClient] = with_default_timeout,
+) -> Benchling:
+    """
+    Factory for creating a Benchling SDK client.
+
+    Args:
+        url (str):
+            Benchling tenant base URL (e.g. https://acme.benchling.com)
+
+        auth:
+            Authentication method compatible with Benchling SDK
+            (e.g. ClientCredentialsOAuth2)
+
+        client_decorator (callable):
+            Optional decorator to customize the underlying API client
+            (timeouts, retries, logging, etc.)
+
+    Returns:
+        Benchling:
+            Configured Benchling SDK client
+    """
+    return Benchling(
+        url=url,
+        auth_method=auth,
+        client_decorator=client_decorator,
+        retry_strategy=with_backoff_timeout(),
+    )

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/context/benchling_context.py

@@ -0,0 +1,56 @@
+from functools import cache
+from typing import Optional
+
+from benchling_sdk.benchling import Benchling
+from benchling_sdk.apps.framework import App
+from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2
+from benchling_sdk.models.webhooks.v0 import WebhookEnvelopeV0
+
+from mgtx_benchling_wrapper.client.benchling_client import create_benchling_client
+
+
+class BenchlingContext:
+    """
+    Unified authentication + tenant context.
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        base_url: str,
+        token_url: Optional[str] = None,
+        app_id: Optional[str] = None,
+    ):
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._base_url = base_url
+        self._token_url = token_url
+        self._app_id = app_id
+
+    @cache
+    def _auth(self):
+        return ClientCredentialsOAuth2(self._client_id, self._client_secret, self._token_url)
+
+    @cache
+    def benchling(self) -> Benchling:
+        return create_benchling_client(
+            url=self._base_url,
+            auth=self._auth(),
+        )
+
+    @cache
+    def app(self) -> App:
+        if self._app_id is None:
+            raise RuntimeError("App requested but no app_id provided")
+        return App(self._app_id, self.benchling())
+
+    @classmethod
+    def from_webhook(cls, webhook: WebhookEnvelopeV0, *, client_id, client_secret):
+        return cls(
+            client_id=client_id,
+            client_secret=client_secret,
+            base_url=webhook.base_url,
+            app_id=webhook.app.id,
+        )

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/chunking.py

@@ -0,0 +1,6 @@
+def chunk_list(lst: list, chunk_n: int):
+    """
+    Chunking the list into chunks of chunk_n elements.
+    """
+    for i in range(0, len(lst), chunk_n):
+        yield lst[i:i + chunk_n]

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/compare_dataframe_cols.py

@@ -0,0 +1,19 @@
+import pandas as pd
+
+def compare_dataframe_columns(
+        dataframe: pd.DataFrame,
+        new_dataframe: pd.DataFrame,
+        column_name: str
+) -> list[str]:
+
+    list_missing_values = []
+    org_column = list(dataframe[column_name])
+    new_column = list(new_dataframe[column_name])
+
+    for value in org_column:
+        if value in new_column:
+            if value not in list_missing_values:
+                if value is not None:
+                    list_missing_values.append(value)
+
+    return list_missing_values

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/create_blob_payload.py

@@ -0,0 +1,38 @@
+import base64
+import hashlib
+import os.path
+
+def create_image_blob_payload(
+        image_path: str,
+        mime_type="image/png",
+        blob_type="VISUALIZATION"):
+    """
+    Create a payload for uploading an image blob through the API.
+    """
+    try:
+        with open(image_path, "rb") as image_file:
+            image_data = image_file.read()
+    except FileNotFoundError:
+        raise Exception(f"Blob file not found: {image_path}")
+
+    #get name of the image
+    _,tail = os.path.split(image_path)
+
+    name = tail.split(".")[0]
+
+    # Encode the binary data to base64
+    data64 = base64.b64encode(image_data).decode('utf-8')
+
+    # Calculate the MD5 hash of the image data
+    md5_hash = hashlib.md5(image_data).hexdigest()
+
+    # Create the payload
+    payload = {
+        "data64": data64,
+        "md5": md5_hash,
+        "mimeType": mime_type,
+        "name": name,
+        "type": blob_type
+    }
+
+    return payload, name

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/datetime_parser.py

@@ -0,0 +1,43 @@
+import warnings
+import pandas as pd
+import re
+import datetime
+
+def _parse_datetime(value):
+    if pd.isna(value):
+        return None
+
+    if isinstance(value, (pd.Timestamp, datetime.date)):
+        return pd.Timestamp(value)
+
+    if _is_ambiguous_date(value):
+        warnings.warn(
+            f"Ambiguous date format detected '{value}'. "
+            f"Assuming day-first format (DD/MM/YYYY).",
+            UserWarning
+        )
+        return pd.to_datetime(value, errors="raise", dayfirst=True, format='mixed')
+
+    return pd.to_datetime(
+        value,
+        errors="raise",
+        dayfirst=True
+    )
+
+
+def _is_ambiguous_date(value: str) -> bool:
+    """
+    Detect ambiguous numeric date formats like 01/02/2024
+    where both day and month <= 12.
+    """
+    if not isinstance(value, str):
+        return False
+
+    pattern = r"^\d{1,2}[/-]\d{1,2}[/-]\d{4}$"
+    if not re.match(pattern, value.strip()):
+        return False
+
+    parts = re.split(r"[/-]", value)
+    day, month, _ = map(int, parts)
+
+    return day <= 12 and month <= 12

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/deprecated.py

@@ -0,0 +1,78 @@
+import functools
+import inspect
+import warnings
+
+string_types = (type(b''), type(u''))
+
+
+def deprecated(reason):
+    """
+    This is a decorator which can be used to mark functions
+    as deprecated. It will result in a warning being emitted
+    when the function is used.
+    """
+
+    if isinstance(reason, string_types):
+
+        # The @deprecated is used with a 'reason'.
+        #
+        # .. code-block:: python
+        #
+        #    @deprecated("please, use another function")
+        #    def old_function(x, y):
+        #      pass
+
+        def decorator(func1):
+
+            if inspect.isclass(func1):
+                fmt1 = "Call to deprecated class {name} ({reason})."
+            else:
+                fmt1 = "Call to deprecated function {name} ({reason})."
+
+            @functools.wraps(func1)
+            def new_func1(*args, **kwargs):
+                warnings.simplefilter('always', DeprecationWarning)
+                warnings.warn(
+                    fmt1.format(name=func1.__name__, reason=reason),
+                    category=DeprecationWarning,
+                    stacklevel=2
+                )
+                warnings.simplefilter('default', DeprecationWarning)
+                return func1(*args, **kwargs)
+
+            return new_func1
+
+        return decorator
+
+    elif inspect.isclass(reason) or inspect.isfunction(reason):
+
+        # The @deprecated is used without any 'reason'.
+        #
+        # .. code-block:: python
+        #
+        #    @deprecated
+        #    def old_function(x, y):
+        #      pass
+
+        func2 = reason
+
+        if inspect.isclass(func2):
+            fmt2 = "Call to deprecated class {name}."
+        else:
+            fmt2 = "Call to deprecated function {name}."
+
+        @functools.wraps(func2)
+        def new_func2(*args, **kwargs):
+            warnings.simplefilter('always', DeprecationWarning)
+            warnings.warn(
+                fmt2.format(name=func2.__name__),
+                category=DeprecationWarning,
+                stacklevel=2
+            )
+            warnings.simplefilter('default', DeprecationWarning)
+            return func2(*args, **kwargs)
+
+        return new_func2
+
+    else:
+        raise TypeError(repr(type(reason)))

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/fields.py

@@ -0,0 +1,15 @@
+def create_fields_dict(
+        list_field_names: list,
+        list_field_values: list
+) -> dict:
+    """ Creates a dictionary with the format {field_name:'value':{field_value}}
+    Args:
+        list_field_names (list): list containing the field names (usually the column names of dataframe)
+        list_field_values (list): values of the fields (usually a row in a dataframe)
+    Return:
+        final_dict (dict): a dictionary of the format to input in fields.
+    """
+    list_word_value = ['value'] * len(list_field_names)
+    final_dict = {u: {v: w} for (u, v, w) in zip(list_field_names, list_word_value, list_field_values)}
+
+    return final_dict

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/list_unique_values_col.py

@@ -0,0 +1,11 @@
+import pandas as pd
+
+def list_unique_values_in_column(
+        dataframe: pd.DataFrame,
+        column_name: str,
+        drop_na: bool = False
+) -> list[str]:
+    if drop_na:
+        return dataframe[column_name].dropna().unique().tolist()
+    else:
+        return dataframe[column_name].unique().tolist()

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/logger.py

@@ -0,0 +1,38 @@
+import logging
+
+def get_logger(name: str, file_log_level: str | int, console_log_level: str | int, console_filter: str | None = None) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)
+
+    # Factory function for creating level filters
+    def level_filter(level_name: str):
+        def filter_func(record):
+            return record.levelname == level_name
+        return filter_func
+
+    # Create formatters
+    console_format = logging.Formatter('%(asctime)s | %(name)s | %(levelname)s | line:%(lineno)d | %(message)s')
+    file_format = logging.Formatter('%(asctime)s | %(name)s | %(levelname)s | %(message)s')
+
+
+    # initiating a console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel((console_log_level))
+    console_handler.setFormatter(console_format)
+    # Add filter if specified
+    if console_filter:
+        console_handler.addFilter(level_filter(console_filter))
+
+    # initiating a file handler
+    file_handler = logging.FileHandler(
+        filename='app.log',
+        mode='a',
+        encoding='utf-8')
+    file_handler.setLevel((file_log_level))
+    file_handler.setFormatter(file_format)
+
+    # add the handlers to the logger
+    logger.addHandler(console_handler)
+    logger.addHandler(file_handler)
+
+    return logger

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/substitute_df_col_dict.py

@@ -0,0 +1,10 @@
+import pandas as pd
+
+def substitute_with_dict(
+        dataframe: pd.DataFrame,
+        column_name: str,
+        dict_orig_to_api: dict
+) -> pd.DataFrame:
+    dataframe[column_name] = dataframe[column_name].replace(dict_orig_to_api)
+
+    return dataframe

mgtx_benchling_wrapper-0.1.0/src/mgtx_benchling_wrapper/utils/validation_summary.py

@@ -0,0 +1,23 @@
+from mgtx_benchling_wrapper.workflows.models.types import ValidationResult
+
+def get_validation_summary(result: ValidationResult) -> str:
+    """Generate human-readable validation summary."""
+    if result.is_valid:
+        summary = "✓ Validation passed"
+        if result.warnings:
+            summary += f" with {len(result.warnings)} warning(s)"
+        return summary
+
+    summary = f"✗ Validation failed with {len(result.errors)} error(s):\n"
+
+    for i, error in enumerate(result.errors, 1):
+        summary += f"\n{i}. {error.message}"
+        if hasattr(error, 'context') and error.context:
+            summary += f"\n   Context: {error.context}"
+
+    if result.warnings:
+        summary += f"\n\nWarnings ({len(result.warnings)}):\n"
+        for warning in result.warnings:
+            summary += f"  - {warning}\n"
+
+    return summary