Base

class LabGuruAPI._base.LGInt(*args, **kwargs)[source]
__init__(default_value: T | None = None, lg_name: str | None = None)[source]

Base class used link python properties with LabGuru integer properties

Parameters:

  • default_value – The value to be supplied to LG if it has not been set elsewhere

  • lg_name – The name of the LabGuru field used in searches. Only necessary if the search name is different from the property name

class LabGuruAPI._base.LGFloat(*args, **kwargs)[source]
base_type

alias of float

__init__(default_value: T | None = None, lg_name: str | None = None)[source]

Base class used link python properties with LabGuru non-integer numeric properties

Parameters:

  • default_value – The value to be supplied to LG if it has not been set elsewhere

  • lg_name – The name of the LabGuru field used in searches. Only necessary if the search name is different from the property name

class LabGuruAPI._base.LGStr(*args, **kwargs)[source]
base_type

alias of str

__init__(default_value: T | None = None, lg_name: str | None = None)[source]

Base class used link python properties with LabGuru string properties

Parameters:

  • default_value – The value to be supplied to LG if it has not been set elsewhere

  • lg_name – The name of the LabGuru field used in searches. Only necessary if the search name is different from the property name

class LabGuruAPI._base.LGJSONStr(*args, **kwargs)[source]
base_type

alias of str

__init__(default_value: T | None = None, lg_name: str | None = None)[source]

Base class used link python properties with LabGuru JSON properties with a Python string implementation

Parameters:

  • default_value – The value to be supplied to LG if it has not been set elsewhere

  • lg_name – The name of the LabGuru field used in searches. Only necessary if the search name is different from the property name

class LabGuruAPI._base.LGList[source]
base_type

alias of int

class LabGuruAPI._base.LGStrList[source]
base_type

alias of str

class LabGuruAPI._base.LGBool(*args, **kwargs)[source]
base_type

alias of bool

__init__(default_value: T | None = None, lg_name: str | None = None)[source]

Base class used link python properties with LabGuru boolean properties

Parameters:

  • default_value – The value to be supplied to LG if it has not been set elsewhere

  • lg_name – The name of the LabGuru field used in searches. Only necessary if the search name is different from the property name

class LabGuruAPI._base.LGDict(*args, **kwargs)[source]
base_type

alias of dict

__init__(default_value: T | None = None, lg_name: str | None = None)[source]

Base class used link python properties with LabGuru JSON properties with a Python dict implementation

Parameters:

  • default_value – The value to be supplied to LG if it has not been set elsewhere

  • lg_name – The name of the LabGuru field used in searches. Only necessary if the search name is different from the property name

class LabGuruAPI._base.LGI

TypeVar shortcut for all LabGuruItem subclasses

alias of TypeVar(‘LGI’, bound=LabGuruItem)

exception LabGuruAPI._base.LGDuplicateNameError[source]
class LabGuruAPI._base.Session(token: str | None = None)[source]

An object that is used to interface with the LabGuru REST API

__init__(token: str | None = None)[source]

An object that is used to interface with the LabGuru REST API

Parameters:

token – The API token used to manage the session.

cache: Dict[SessionCacheKey, LGI]

A cache of LabGuruItems to reduce the number of queries to the LabGuru API

transactions: List[SessionTransaction]

Currently unused

config

Interface for the backend config file

property token

The token used to authenticate API calls

login() → str[source]

Checks the validity of a cached API token and refreshes it if necessary

Returns:

The current API token

get_config_value(section: str, key: str, ask=False) → str[source]

Retrieves a configuration value from the config file.

Parameters:

  • section – Config file section

  • key – Config key to retrieve

  • ask – If true, prompts the user for a value if the key is not found. Will store and return the value.

Returns:

The configuration value string

Raises:

KeyError – The configuration Section or Key does not exist if the ask parameter is False

set_config_value(section: str, key: str, value: Any)[source]

Writes a key-value pair to the configuration file.

Parameters:

  • section – Config file section

  • key – Config key to set

  • value – Value of the config key. Will be converted to a string before writing

make_api_path(endpoint: str, with_token: bool = False) → str[source]

Formats an API path with a given endpoint.

Parameters:

  • endpoint – The API endpoint to be called. Will prepend ‘https://my.labguru.com/api/v1/’ if not included.

  • with_token – if True, adds the current token as a URL parameter

Returns:

The formatted API URL

add(item: LGI) → LGI[source]

Adds an item to the LG database. Updates the cache.

Parameters:

item – The LabGuruItem to be added

Returns:

A freshly-queried version of the added item

async aio_add(item: LGI) → LGI[source]

Asynchronously adds an item using a separate thread executor and returns the result. If an exception occurs during execution, the error information is captured and returned as an LGIError.

Parameters:

item – The LGI instance to be added.

Returns:

The result of the addition if successful, otherwise an LGIError containing the exception information and a dictionary representation of the item.

Return type:

LGI

add_many(items: List[LGI]) → List[LGI][source]

Adds a list of items to the database in parallel. Updates the cache.

Parameters:

items – A list of LabGuruItem objects to be added to the database

Returns:

A freshly-queried list of the added items. The input object order is preserved.

update(item: LGI) → LGI[source]

Updates an item in the LG database. Updates the cache.

Parameters:

item – The LabGuruItem to be updated

Returns:

A freshly-queried version of the updated item

async aio_update(item: LGI) → LGI[source]

Updates an LGI item asynchronously using an executor.

This method utilizes Python’s asyncio library to execute the update method asynchronously in a separate thread. It is useful when performing non-blocking I/O operations that involve updating an LGI item.

Parameters:

item – The LGI object that needs to be updated. It must adhere to the LGI interface, providing a to_dict method.

Returns:

Returns an updated LGI object if the update is successful. In the event of an exception during execution, an LGIError containing the exception information and the original item’s dictionary form is returned.

Return type:

LGI

update_many(items: List[LGI], delay=0.1) → List[LGI][source]

Updates a list of items in the database in parallel. Updates the cache.

Parameters:

items – A list of LabGuruItem objects to be updated

Returns:

A freshly-queried list of the updated items. The input object order is preserved.

refresh(item: LGI) → LGI[source]

Forces a re-query of a LabGuruItem. Replaces the cached version with the new item.

Parameters:

item – the LabGuruItem to be refreshed

Returns:

the refreshed LabGuruItem

delete(item: LGI) → bool[source]

Removes an item from the LG database and the session cache. This is irreversible.

Parameters:

item – The LabGuruItem to be deleted.

Returns:

True if the request succeeded.

archive(item: LGI) → bool[source]

Archives an item in the LG database. Not available for all items.

Parameters:

item – The LabGuruItem to be archived.

Returns:

True if the request succeeded.

async aio_archive(item: LGI) → bool[source]

Archives the specified item asynchronously by making an asynchronous HTTP PUT request to the item’s API endpoint. The method constructs the request using the provided item’s ID and a token for authentication.

Parameters:

item (LGI) – The item to be archived, represented as an instance of LGI class.

Returns:

Returns True if the item was archived successfully, otherwise False.

Return type:

bool

restore(item: LGI) → bool[source]

Restores an archived item in the LG database. Not available for all items.

Parameters:

item – The LabGuruItem to be restored.

Returns:

True if the request succeeded.

dump_cache(verbose=True) → DefaultDict[str, List[Dict]][source]

Dumps the contents of the cache into a dictionary of lists categorized by class display names. This function iterates over unique cached items and converts them into dictionary format, organizing them according to their display name.

Parameters:

verbose (bool) – If True, displays a progress bar using tqdm to show the progress of dumping the cache. If False, the progress bar is disabled.

Returns:

A dictionary where each key is the class display name and the value is a list of dictionaries representing cached items of that class.

Return type:

DefaultDict[str, List[Dict]]

load_cache(dump: DefaultDict[str, List[Dict]], verbose=True)[source]

Loads cache from a given data structure and populates internal storage.

Iterates over a provided dictionary, mapping class names to lists of item data. For each class name, it attempts to retrieve the corresponding class from a predefined collection. If a class is found, it parses each item data using the class-specific parsing method and adds the resulting item to the cache. Progress through the process can optionally be displayed.

Parameters:

  • dump – A defaultdict where keys are class names (str) and values are lists of dictionaries representing item data.

  • verbose – A boolean indicating whether to display progress information during the caching process.

execute_async(awaitables: List[Awaitable[LGI | None]], task_limit=5, verbose=True) → List[LGI | None][source]

Executes a set of asynchronous tasks with a limit on the number of concurrent tasks, and optionally displays a progress bar.

Parameters:

  • awaitables – A list of awaitable objects that represent the asynchronous tasks to be executed.

  • task_limit – An integer that sets the maximum number of tasks that can be run concurrently.

  • verbose – A boolean flag to control the display of a progress bar; if True, the progress bar is shown.

async aio_get_object(lgi_class: Type[LGI], item_id: int | None = None, name: str | None = None, uuid: str | None = None, api_url: str | None = None, auto_name: str | None = None, include_custom=False, from_cache=True) → LGI[source]

Asynchronously retrieves an object of the specified LGI class using provided identifying criteria or API URL. The object is fetched from cache if available; otherwise, it is retrieved from the API.

Parameters:

  • lgi_class – The LGI class type that determines the type of object to retrieve.

  • item_id – The identifier of the item to be fetched. Defaults to None.

  • name – The name of the item to be retrieved. Defaults to None.

  • uuid – The universally unique identifier of the item. Defaults to None.

  • api_url – The API URL to directly fetch the item from. May include percent encoding, which will be replaced. Defaults to None.

  • auto_name – The automatic name used in fetching the object. Defaults to None.

  • include_custom – A boolean indicating whether to include custom fields when retrieving the object. Defaults to False.

  • from_cache – A boolean indicating whether to attempt fetching the object from cache before contacting the API. Defaults to True.

Returns:

An instance of LGI corresponding to the specified criteria if found, or an LGIError instance if an error occurs during fetching or processing.

async aio_get_from_name(potential_classes: List[Type[LGI]], item_name: str) → LGI | None[source]

Asynchronously attempts to retrieve an item by its name from a list of potential classes. This function concurrently queries each class for the desired item and returns the first matching item found.

Parameters:

  • potential_classes (List[Type[LGI]]) – A list of classes that are potential candidates from which the item might be retrieved. Each class should offer a method for obtaining an item by name.

  • item_name (str) – The name of the item to be retrieved. This is the identifying string used to search for the item within each provided class.

Returns:

The first item found that matches the given name, if any; otherwise, returns None if no matching item is found across all provided classes.

Return type:

Optional[LGI]

get_object(lgi_class: Type[LGI], item_id: int | None = None, name: str | None = None, uuid: str | None = None, api_url: str | None = None, auto_name: str | None = None, include_custom=False, from_cache=True, proxy=True) → LGI[source]

Retrieves a LabGuruItem from the API. Only 1 of the following parameters will be queried, in the following order: item_id, name, uuid, auto_name.

Parameters:

  • lgi_class – The python class of the desired item

  • item_id – The database id of the desired item

  • name – The name of the desired item

  • uuid – The uuid of the desired item

  • api_url – The API URL of the desired item

  • auto_name – The SysID of the desired item

  • include_custom – If true, include the ~200 “custom###” fields returned by the api. Default: False

  • from_cache – If false, forces an API call even if the object is cached. Default: True

  • proxy – If true, returns a proxy object with lazy API calls. Default: True

Returns:

The requested LabGuruItem

get_many(lgi_class: Type[LGI], item_ids: List[int] | None = None, names: List[str] | None = None, uuids: List[str] | None = None, api_urls: List[str] | None = None, auto_names: List[str] | None = None, include_custom=False, from_cache=True) → List[LGI][source]

Retrieves a list of LabGuruItem objects from the API. Only 1 of the following parameters will be queried, in the following order: item_ids, names, uuids, auto_names.

Parameters:

  • lgi_class – The python class of the desired items

  • item_ids – The database ids of the desired items

  • names – The names of the desired items

  • uuids – The uuids of the desired items

  • api_urls – The API URLs of the desired items

  • auto_names – The SysIDs of the desired items

  • include_custom – If true, include the ~200 “custom###” fields returned by the api. Default: False

  • from_cache – If false, forces an API call even if the object is cached. Default: True

Returns:

The requested LabGuruItem objectss

async get_all_dicts(lgi_class: Type[LGI], page_size: int = 10)[source]

Retrieves an entire collection.

Parameters:

  • lgi_class – The python class to be queried

  • page_size – number of objects to return per api call

Returns:

the JSON representation of all queried objects

search_api(item_type: Type[LGI], field_name: str, operator: str, value: Any, page_size: int = 100) → List[LGI][source]

Deprecated since version Please: use LabGuruItem.find_all or LabGuruItem.find_one

aio_search_api(item_type: Type[LGI], field_name: str, operator: str, value: Any, page_size: int = 100) → List[LGI][source]

Deprecated since version Please: use LabGuruItem.async_find_all or LabGuruItem.async_find_one

Creates a link between LG items

Parameters:

  • from_item – a LabGuruItem

  • to_item – a LabGuruItem

Returns:

True if the link is successful

Creates a link between LG items

Parameters:

  • from_item – a LabGuruItem

  • to_item – a LabGuruItem

Returns:

True if the link is successful

get(endpoint: str, **data) → Dict[str, Any] | None[source]

Sends a GET request to a specified API endpoint using given data and returns the response as a JSON object if the request is successful.

The method appends the authentication token to the request data and sends a GET request to the constructed API path using the input endpoint and additional data. If the response status is successful, it returns the response content as a JSON object. Otherwise, it returns None.

Parameters:

  • endpoint – The API endpoint to send the GET request to.

  • **data – Additional data to be included in the request. This data will be sent as a JSON object in the GET request.

Returns:

A dictionary containing the JSON response data if the request is successful. Returns None if the request fails.

async aio_get(endpoint: str, c_session: ClientSession | None = None, retries=3, **data) → Dict[str, Any] | None[source]

Performs an asynchronous GET request to a specified API endpoint with optional retry logic.

Parameters:

  • endpoint – The API endpoint to which the GET request is sent.

  • c_session – An optional aiohttp.ClientSession to be used for the request. A new session is created if not provided.

  • retries – The number of times the request should be retried upon encountering server errors (HTTP status 500 and above).

  • **data – Additional data to be included in the request, specifically a ‘token’ is added from the instance attribute for authorization.

Returns:

An optional dictionary containing the JSON response from the API if the request is successful; otherwise, None.

post(endpoint: str, **data) → Dict[str, Any] | None[source]

Sends a POST request to the provided API endpoint with the given data and a token. The method constructs the full API path from the endpoint, adds a token to the request data, and sends the POST request. If the request is successful, the response is parsed as JSON and returned. Otherwise, returns None.

Parameters:

  • endpoint (str) – The API endpoint to which the POST request is sent.

  • **data – Arbitrary keyword arguments representing the request body to be sent in JSON format.

Returns:

Parsed JSON response from the POST request if successful; otherwise, None.

Return type:

Optional[Dict[str, Any]]

put(endpoint: str, **data) → Dict[str, Any] | None[source]

Updates a resource using a HTTP PUT request to the specified endpoint of the API with the provided data, appending the authentication token to the payload. Returns the parsed JSON response if the request is successful, otherwise returns None.

Parameters:

  • endpoint (str) – The API endpoint to send the PUT request to.

  • **data – Arbitrary keyword arguments representing the data to be included in the PUT request.

Returns:

The parsed JSON response from the API if the request is successful, otherwise None.

Return type:

Optional[Dict[str, Any]]

del_request(endpoint: str, **data) → Dict[str, Any] | None[source]

Sends a DELETE request to a specified API endpoint with additional data.

This function constructs the endpoint path using the provided endpoint and sends a DELETE request. The token is automatically included in the data payload. If the request is successful, it returns the JSON response as a dictionary. Otherwise, it returns None.

Parameters:

  • endpoint – The API endpoint to which the DELETE request will be sent.

  • **data – Arbitrary keyword arguments to be included in the request payload. These will be merged with the authentication token.

Returns:

The JSON response as a dictionary if the request is successful, or None if the request fails.

Return type:

Optional[Dict[str, Any]]

async aio_put(endpoint: str, **data) → Dict[str, Any] | None[source]

Sends an asynchronous HTTP PUT request to the specified API endpoint with the provided data.

This method constructs an API path using the specified endpoint and sends a PUT request including any provided keyword arguments in the JSON payload. Additionally, it adds an authentication token to the data payload. If the server responds with an HTTP status code indicating success, it parses and returns the JSON response. Otherwise, it returns None.

Parameters:

  • endpoint (str) – The API endpoint to which the PUT request is sent.

  • **data – Arbitrary keyword arguments representing additional data to be included in the request payload.

Returns:

The JSON response as a dictionary if the request is successful, or None if the response indicates failure.

Return type:

Optional[Dict[str, Any]]

async aio_post(endpoint: str, **data) → Dict[str, Any] | None[source]

Sends an asynchronous POST request to a specified endpoint with JSON data.

This method is designed for making POST requests to a specified API endpoint, including a token within the request payload. It uses an asynchronous HTTP session to perform the operation and returns the parsed JSON response if the request is successful. If the request fails, it returns None.

Parameters:

  • endpoint (str) – The API endpoint to which the POST request is sent.

  • **data – Additional keyword arguments containing the JSON data to include in the request body.

Returns:

The parsed JSON response from the server if the

request is successful, or None if the request fails.

Return type:

Optional[Dict[str, Any]]

async aio_delete(endpoint: str) → bool[source]

Sends an asynchronous HTTP DELETE request to the specified API endpoint.

This method uses an asynchronous HTTP client session to send a DELETE request to the given endpoint. It returns a boolean value indicating whether the request was successful or not.

Parameters:

endpoint (str) – The API endpoint to which the DELETE request will be sent.

Returns:

True if the response status indicates success (HTTP 2xx), False otherwise.

Return type:

bool

get_members() → Dict[str, int][source]

Retrieves a mapping of all member names to their IDs :return: A dictionary whose keys are names and values are member IDs

class LabGuruAPI._base.LabGuruItem(**kwargs)[source]

A base class for all objects retrieved from the LabGuru Database

class_name

The programmatic class name for the LG API

class_display_name

The human-readable class name for the LG API

uuid

A unique identifier string of the object. Searchable.

id

The database ID of the object. Searchable.

name

The name/title of the object. Searchable.

owner_id

The database ID of the object’s owner. Searchable.

description

A description of the object. Searchable.

api_url

The object’s REST API URL. Searchable.

auto_name

The object’s SysID. Searchable.

xlsx_collection = 'Generic'

The Dataset header/Plate upload name for the object class

property web_url

The web-interface URL for the object

classmethod isinstance(other: LGI) → bool[source]

Check if an object is an instance of this class

classmethod make_new(overwrite=False, **properties) → LGI[source]

Creates a new item without adding it to the database :param overwrite: if true, will get an object by the same name if it exists and overwrite that object :param properties: The initial properties of the object :return: A new instance of the class

classmethod add_new(overwrite=False, **properties) → LGI[source]

Creates a new item AND adds it to the database

Parameters:

properties – The initial properties of the object

Returns:

A new instance of the class

make_new_copy() → LGI[source]

Creates a copy of the object excluding the database ids and name

classmethod get_attribute_dict(capitalize=False)[source]

Generates a full LG -> python mapping of all class-specific and inherited properties

classmethod get_api_url() → str[source]

Returns the API url for the class

classmethod item_api_url(item_id: int, omit_json=False)[source]

Generates an API URL for a specific item of this class. :param item_id: the item’s database ID :param omit_json: if true, drops the ‘.json’ from the end of the URL (Default: False) :return: the URL string

static process_api_url(url: str, omit_json=False)[source]

Coerces an API url into the correct format

classmethod parse_api_data(json_data: ~typing.Dict[str, ~typing.Any], session: ~LabGuruAPI._base.Session = <LabGuruAPI._base.Session object>, include_custom=False) → LGI[source]

Generates a python object from the LabGuru API’s JSON response. This is a low-level function that should not be used routinely.

Parameters:

  • json_data – the JSON dictionary read from the API

  • session – the active LG session. Please leave as the default value.

  • include_custom – add the LG “custom###” fields to LGI.other_properties. Default: false

Returns:

the python version of the LG object

classmethod from_api(session: ~LabGuruAPI._base.Session = <LabGuruAPI._base.Session object>, item_id: int | None = None, name: str | None = None, uuid: str | None = None, api_url: str | None = None, auto_name: str | None = None, include_custom=False) → LGI | None[source]

Low-level function. Please use LabGuruItem.from_LG instead.

classmethod from_LG(item_id: int | None = None, name: str | None = None, uuid: str | None = None, api_url: str | None = None, auto_name: str | None = None, include_custom=False, from_cache=True, proxy=True) → LGI[source]

Retrieves a LabGuruItem from the API. Only 1 of the following parameters will be queried, in the following order: item_id, name, uuid, auto_name.

Note: This should only be used if LabGuruItem.from_name or LabGuruItem.from_id is insufficient.

Parameters:

  • item_id – The database id of the desired item

  • name – The name of the desired item

  • uuid – The uuid of the desired item

  • api_url – The API URL of the desired item

  • auto_name – The SysID of the desired item

  • include_custom – If true, include the ~200 “custom###” fields returned by the api. Default: False

  • from_cache – If false, forces an API call even if the object is cached. Default: True

  • proxy – If true, returns a proxy object with lazy API calls. Default: True

Returns:

The requested LabGuruItem

async classmethod async_from_LG(item_id: int | None = None, name: str | None = None, uuid: str | None = None, api_url: str | None = None, auto_name: str | None = None, include_custom=False, from_cache=True) → LGI[source]

Retrieves a LabGuruItem from the API. Only 1 of the following parameters will be queried, in the following order: item_id, name, uuid, auto_name.

Note: This should only be used if LabGuruItem.async_from_name or LabGuruItem.async_from_id is insufficient.

Parameters:

  • item_id – The database id of the desired item

  • name – The name of the desired item

  • uuid – The uuid of the desired item

  • api_url – The API URL of the desired item

  • auto_name – The SysID of the desired item

  • include_custom – If true, include the ~200 “custom###” fields returned by the api. Default: False

  • from_cache – If false, forces an API call even if the object is cached. Default: True

Returns:

The requested LabGuruItem

classmethod from_name(name: str) → LGI[source]

Retrieves a LabGuruItem from the API via its name.

Examples

Get plasmid pGRO-S0081:

p = Plasmid.from_name('pGRO-S0081')
Parameters:

name – The exact name of the desired item

Returns:

The requested LabGuruItem

async classmethod async_from_name(name: str) → LGI[source]

Retrieves a LabGuruItem from the API via its name.

Examples

Get plasmid pGRO-S0081:

p_future = Plasmid.async_from_name('pGRO-S0081')
Parameters:

name – The exact name of the desired item

Returns:

The requested LabGuruItem

classmethod from_names(names: List[str], verbose: bool = True) → List[LGI][source]

Retrieves a list of LabGuruItem objects from the API. This is done in parallel, so it will be faster than individual LGI.from_name() calls.

Examples

Retrieve all the plasmids listed in a DataFrame column:

p_names = dframe['Plasmids'].unique()
plasmids = Plasmid.from_names(p_names)
Parameters:

  • names – a list of object names

  • verbose – if true, a progress bar will be written to stdio while gathering the items

Returns:

the requested list of items

classmethod from_id(item_id: int | str) → LGI[source]

Retrieves a LabGuruItem from the API via its ID number.

Examples

Get plasmid pGRO-S0081:

p = Plasmid.from_id(294)
Parameters:

item_id – The database id of the desired item

Returns:

The requested LabGuruItem

async classmethod async_from_id(item_id: int | str) → LGI[source]

Retrieves a LabGuruItem from the API via its ID Number.

Examples

Get plasmid pGRO-S0081:

p_future = Plasmid.async_from_id(294)
Parameters:

item_id – The database id of the desired item

Returns:

The requested LabGuruItem

classmethod from_ids(ids: List[int | str], verbose: bool = True) → List[LGI][source]

Retrieves a list of LabGuruItem objects from the API. This is done in parallel, so it will be faster than individual LGI.from_name() calls.

Examples

Retrieve all the plasmids listed in a DataFrame column:

p_ids = dframe[‘Plasmid_ids’].unique() plasmids = Plasmid.from_ids(p_ids)

Parameters:

  • ids – a list of database ids

  • verbose – if true, a progress bar will be written to stdio while gathering the items

Returns:

the requested list of items

classmethod search_api(session: Session, query_data: Dict[str, Any]) → List[LGI][source]

Deprecated since version Please: use LabGuruItem.find_all or LabGuruItem.find_one

classmethod aio_search_api(session: Session, query_data: Dict[str, Any], cur_page=1) → List[LGI][source]

Deprecated since version Please: use LabGuruItem.async_find_all or LabGuruItem.async_find_one

to_dict(include_other_properties=True, include_links=True, include_id=True) → Dict[str, Any][source]

Generates a mapping of LG property fields to values for the object. Generally used for add/update calls.

Parameters:

  • include_other_properties – adds fields contained in other_properties to the dictionary.

  • include_links – will include the links and tags fields in the output dictionary

  • include_id – will include the item’s ID it the output dictionary

Returns:

a dictionary mapping of LG property fields to values

update_api(session: Session, retries=0) → LGI[source]

Low-level function, please do not use. LabGuruItem.lg_sync is likely the method you want.

lg_sync() → LGI[source]

Adds or updates the item in the LG database.

async async_lg_sync() → LGI[source]

Adds or updates the item in the LG database. Be careful not to queue multiple syncs per item as the final object may not reflect all updates or may be added multiple times.

find_attachments() → List[Attachment][source]

Returns a list of Attachment objects associated with the item.

classmethod find_next_id(prefix: str) → int[source]

Searches the database for names beginning with a specified prefix, determines the associated index and gives the next number

Parameters:

prefix – The prefix of the indexed samples (ex: “GBFP-0927-“)

Returns:

the integer index following the last entered sample

classmethod make_id_iterator(prefix: str) → Iterator[int][source]

Searches the database for names beginning with a specified prefix, determines the associated index, and yields subsequent indexes on each iteration

Parameters:

prefix – The prefix of the indexed samples (ex: “GBFP-0927-“)

Returns:

sequential integers beginning with the first unused index number

classmethod iter_next_names(prefix: str, zeros: int = 4) → Iterator[str][source]

Searches the database for names beginning with a specified prefix, determines the associated index, and yields subsequent names on each iteration

Example

You need to add temporary strains for experiment 6294. Currently, LG has 27 strains for this experiment, so the largest temporary strain name is “GBFS-6294-0027”.

name_iter = Strain.iter_next_names("GBFS-6294-", 4)
for _ in range(3):
    print(next(name_iter))

# Results
# GBFS-6294-0028
# GBFS-6294-0029
# GBFS-6294-0030
Parameters:

  • prefix – The prefix of the indexed samples (ex: “GBFP-0927-“)

  • zeros – The number of digits used by the index. Default: 4

Returns:

sequential formatted names beginning with the first unused index number

Links the current item to the target item in LabGuru :param link_target: the LabGuruItem to link :return: True if the link is successful

Links the current item to the target item in LabGuru :param link_target: the LabGuruItem to link :return: True if the link is successful

get_linked_items(of_type: Type[LGI]) → List[LGI][source]

Queries LG for items of a particular class that are linked to the current item.

Parameters:

of_type – the class of LabGuruItem you would like returned

Returns:

a list of linked LabGuruItem objects

async async_get_linked_items(of_type: Type[LGI]) → List[LGI][source]

Queries LG for items of a particular class that are linked to the current item.

Parameters:

of_type – the class of LabGuruItem you would like returned

Returns:

a list of linked LabGuruItem objects

get_derived_items(of_type: Type[LGI]) → List[LGI][source]

Queries LG for items of a particular class that are derived from the current item

Parameters:

of_type – the class of LabGuruItem you would like returned

Returns:

a list of derived LabGuruItem objects

async classmethod async_count_all(*search_operators: LGSearchOperator) → int[source]

AsyncIO-compatible version of LabGuruItem.count_all()

Parameters:

search_operators – Comparison operators that will be used as filters in the LabGuru query

Returns:

A list of LabGuruItem objects that match all the provided filters

async classmethod async_find_all(*search_operators: LGSearchOperator) → List[LGI][source]

AsyncIO-compatible version of LabGuruItem.find_all()

Parameters:

search_operators – Comparison operators that will be used as filters in the LabGuru query

Returns:

A list of LabGuruItem objects that match all the provided filters

classmethod find_all(*search_operators: LGSearchOperator) → List[LGI][source]

Searches the LabGuru API for all objects that match the search operators. All properties that can be used in searches will be called out directly in their own documentation.

Parameters:

*search_operators – Comparison operators that will be used as filters in the LabGuru query

Returns:

A list of LabGuruItem objects that match all the provided filters

Examples

Finding all pGRO plasmids that were generated as part of experiment 818:

results = Plasmid.find_all(Plasmid.name.contains('pGRO'), Plasmid.clone_no.contains('GBFP-0818-'))

Finding all strains that express Uox25 variants:

results = Strain.find_all(Strain.description.contains('Uox25'))

Finding all overnight culture plates from experiment 927:

results = Plate.find_all(Plate.name.starts_with('0927-ONC'))
async classmethod async_find_one(*search_operators: LGSearchOperator) → LGI | None[source]

AsyncIO-compatible version of LabGuruItem.find_one()

Parameters:

search_operators – Comparison operators that will be used as filters in the LabGuru query

Returns:

The first LabGuruItem object that matches all the provided filters

classmethod find_one(*search_operators: LGSearchOperator) → LGI | None[source]

Searches the LabGuru API for all objects that match the search operators and returns the first match. All properties that can be used in searches will be called out directly in their own documentation.

Parameters:

*search_operators – Comparison operators that will be used as filters in the LabGuru query

Returns:

The first LabGuruItem object that match all the provided filters

Examples

Find the largest biomass pellet from GRO20-1895 that was grown in TB:

s = Strain.from_name('GRO20-1895')
result = BiomassPellet.find_one(BiomassPellet.parent_strain == s, BiomassPellet.pellet_weight.desc())
class LabGuruAPI._base.LGIError(exception_info: Tuple[Type[BaseException], BaseException, TracebackType], errored_item_dict: Dict, **kwargs)[source]
to_dict(**kwargs) → Dict[str, Any][source]

Generates a mapping of LG property fields to values for the object. Generally used for add/update calls.

Parameters:

  • include_other_properties – adds fields contained in other_properties to the dictionary.

  • include_links – will include the links and tags fields in the output dictionary

  • include_id – will include the item’s ID it the output dictionary

Returns:

a dictionary mapping of LG property fields to values

update_api(session: Session, retries=0) → LGI[source]

Low-level function, please do not use. LabGuruItem.lg_sync is likely the method you want.

get_linked_items(of_type: Type[LGI]) → List[LGI][source]

Queries LG for items of a particular class that are linked to the current item.

Parameters:

of_type – the class of LabGuruItem you would like returned

Returns:

a list of linked LabGuruItem objects

class LabGuruAPI._base.Attachment(attach_to: LGI | None = None)[source]
file

An interactable attachment file

attachable

A dict describing the collection/inventory/ELN item that this file is attached to

get_download_url(session: ~LabGuruAPI._base.Session = <LabGuruAPI._base.Session object>)[source]

Gets the LG URL used to download the attachment file

download(session: ~LabGuruAPI._base.Session = <LabGuruAPI._base.Session object>)[source]

Downloads the file to a temporary folder

make_file(filename: str) → Path[source]

Create a new temporary file with a specific name.

Parameters:

filename – the desired file name

Returns:

a Path to the new file

attach_to(item: LGI)[source]

Sets the attachable dictionary to point to a given LabGuruItem

property attachable_id

The database ID of the attached item. Searchable.

property attachable_class

The programatic class name of the attached item. Searchable.

property attachable_uuid

The database UUID of the attached item. Searchable.

update_api(session: Session, **kwargs) → LGI[source]

Low-level function, please do not use. LabGuruItem.lg_sync is likely the method you want.

class LabGuruAPI._base.Units[source]

A specialized mapping class for managing and converting scientific units.

This class provides an interface for accessing scientific units, their corresponding identifiers, and the ability to convert measurements among equivalent units. The class dynamically fetches unit data from an external API when accessed. It supports iteration, length retrieval, and accessing specific unit information via dictionary-like syntax.

unit_ids

A mapping of unit names to their respective IDs.

Type:

Dict[str, int]

ids_to_units

A reverse mapping of unit IDs to their names.

Type:

Dict[int, str]

unit_types

A mapping of unit IDs to their types/categories.

Type:

Dict[int, str]

property ng_ul: int

Shortcut for the ng/μL unit id

property molar: int

Shortcut for the molar unit id

property millimolar

Shortcut for the millimolar unit id

property micromolar

Shortcut for the micromolar unit id

property nanomolar

Shortcut for the nanomolar unit id

convert(value: float, from_id: int, to_id: int)[source]

Converts a value between units of the same type.

Example

Converting between millimolar & nanomolar:

um = UNITS.convert(1, UNITS.millimolar, UNITS.micromolar)
assert um == 1_000  # True
Parameters:

  • value – the value of the initial unit

  • from_id – the unit ID of the initial value

  • to_id – the unit ID for the desired value

Returns:

the converted unit magnitude

LabGuruAPI._base.UNITS = <LabGuruAPI._base.Units object>

Importable object used to interact with units/unit IDs

class LabGuruAPI._base.HasWells(rows=8, cols=12)[source]

Represents a structure composed of wells arranged in a grid-like positions.

This class provides utilities to work with well grids, allowing the mapping between different well naming conventions and positional systems. It includes methods for converting between well names (e.g., A1, A01), linear grid positions, Tecan positions, as well as to iterate across all valid wells or positions. It also supports operations to handle stocks associated with the wells, which can be abstractly implemented in subclasses.

rows

Number of rows in the grid.

Type:

int

cols

Number of columns in the grid.

Type:

int

well_name_to_position(name: str) → int[source]

Convert a well name (A1) to its correspoinding LG position value

position_to_well_name(position: int, short=False) → str[source]

Convert an LG position value to a well name: (A1 if short=True, A01 if short=False)

position_to_tecan_well(position: int) → int[source]

Convert an LG position value (rowwise indexes) to a Tecan position value (columnwise indexes)

well_name_to_tecan_well(well_name: str) → int[source]

Convert a well name (A1) to its corresponding Tecan position value

tecan_well_to_position(tecan_well: int) → int[source]

Convert a Tecan position value (columnwise indexes) to an LG position value (rowwise indexes)

tecan_well_to_name(tecan_well: int, short: bool = False) → str[source]

Convert a Tecan position value to a well name: (A1 if short=True, A01 if short=False)

iter_positions(rowwise=False) → Iterable[int][source]

Iterate through all available LG position values

iter_well_names(rowwise=False, short=False) → Iterable[str][source]

Iterate through all available well names

iter_tecan_positions(rowwise=False) → Iterable[int][source]

Iterate through all available Tecan position values

abstract stocks_from_position(position: int, **kwargs) → List[Stock][source]

Get a list of all stocks at a specified position

stocks_from_well(well_name: str, **kwargs) → List[Stock][source]

Get a list of all stocks in a specified well

stocks_from_tecan_position(tecan_position: int, **kwargs) → List[Stock][source]

Get a list of all stocks in a specified tecan position

abstract copy_stock_to_position(stock: Stock, position: int) → Stock[source]

Make a copy of a stock and add it to a specified position

copy_stock_to_well(stock: Stock, well_name: str) → Stock[source]

Make a copy of a stock and add it to a specified well

copy_stock_to_tecan_position(stock: Stock, tecan_position: int) → Stock[source]

Make a copy of a stock and add it to a specified well

abstract update_stock_at_position(stock: Stock, position: int) → Stock[source]

Replace a stock at a specified position with a new one

update_stock_at_well(stock: Stock, well_name: str) → Stock[source]

Replace a stock in a specified well with a new one

LabGuruAPI._base.SESSION = <LabGuruAPI._base.Session object>

The global Session object that should always be used to interact with LabGuru.